2016年の発売直後から大きな話題を呼び、中国・ドイツ・韓国・ブラジル・ロシア・ベトナムなど世界各国にも広がった「学び直し本」の圧倒的ロングセラーシリーズ「Big Fat Notebook」の日本版が刊行された。藤原和博氏(朝礼だけの学校 校長)「プログラミングは新しい言語の獲得だ」、野田クリスタル氏(お笑い芸人・マヂカルラブリー)「プログラミングがやりたくなる! まるでゲームの攻略本みたい!」、尾原和啓氏(元グーグル・IT評論家)「プログラミングを通して、ビジネスにも応用できる考え方が見えてくる!」と絶賛されている。本記事では、全世界700万人が感動した同シリーズのプログラミング編『アメリカの中学生が学んでいる 14歳からのプログラミング』より、本文の一部を抜粋・掲載します。
![アメリカの中学生が学ぶドキュメント作成の授業【全世界700万人が感動したプログラミングノート】](https://dol.ismcdn.jp/mwimgs/4/c/600/img_2f27d5f20f45e5c57caa0b817a87599b51372.jpg)
ドキュメントを作成する
ドキュメント(文書)とは、プログラムのコードについて書かれた情報のこと。ドキュメントには主に、コメントとREADME(リードミーファイル)の2種類がある。
コメント
どのプログラミング言語にも、コード内にコメントを追加する方法が用意されている。でも、コメントはプログラムの一部じゃないから、プログラムを実行するときには飛ばされるし、ユーザーの目には見えない。
コメントは、プログラマがそのプログラムのコードについて書き残したメッセージなのだ。あるコードの果たす機能についての説明のこともあるし、追加または変更すべき内容についてのメモのこともある。
あとでそのコードをチェックするプログラマへの質問を書き残す場合もあるのだ。
![アメリカの中学生が学ぶドキュメント作成の授業【全世界700万人が感動したプログラミングノート】](https://dol.ismcdn.jp/mwimgs/2/8/600/img_28ce8d73406b2db5e60525ed375e96f631008.png)
コードにコメントを書き残すと、ある部分のコードがどんな機能を果たすのか覚えておくのに役立つ。特に、巨大なプログラムの場合は便利だ。なぜならどのコードがどう動作するのか、ぜんぶ丸暗記しておかなくてもすむから。
でも、コメントは、短いプログラムでも役立つ。コードを書き終えたずっとあとになって、またそのコードを調べたくなることもあるからだ。
それから、別のプログラムのコードや、きみやだれかが前に書いたコードを再利用したくなることもある。
そんなとき、コメントがついていれば、きみが再利用したいコードをパッと見つけられる。
たとえば、ゲームをつくっているなら、キャラクターを動き回らせるためのコードをきみ自身でつくる代わりに、別のプログラムからコピーすればすむ。
きみのプログラムのなかで、どの部分がキャラクターを動かすためのコードなのかがわかるようにコメントを書き残しておくと便利だろう。
コメントは、プログラムのデバッグにも役立つ。
コメント部分は、プログラムを実行するときには飛ばされるから、バグがひそんでいるかもしれないコードをいきなり削除するんじゃなく、いったんコメントアウトするほうがいい。
コメントアウトされたコードは、実行されないから、そこにバグが存在したかどうかがわかるというわけだ。
![アメリカの中学生が学ぶドキュメント作成の授業【全世界700万人が感動したプログラミングノート】](https://dol.ismcdn.jp/mwimgs/d/c/400/img_dc459286d875e8445bda5130b1ca21ea39916.png)
また、コメントは、テストコードを追加して、デバッグをおこなうのにも役立つ。
テストが終わったら、追加した部分をコメントアウトするだけで元に戻せるからだ。
コメントは、きみ自身へのメモを残すのにも使える。
たとえば、次のような表記を使って、きみ自身への短いメモを残すといいだろう。
#BUGまたは#FIXME―あとで修正しようと思っているバグ。
#TODO―本当は書かなくちゃいけないけど、後回しにしているコードについてのメモ。
README(リードミー)
README(目立つよう、すべて大文字で書くのがふつう)とは、あるプログラムに関する情報が書かれたファイルのこと。
たとえば、プログラムに含まれるファイルの一覧、インストール方法、使い方、著作権情報、判明しているバグなどを書くことが多い。
![アメリカの中学生が学ぶドキュメント作成の授業【全世界700万人が感動したプログラミングノート】](https://dol.ismcdn.jp/mwimgs/0/5/400/img_057673c4ee925fe299252ba3d21bc02874701.png)
READMEファイルは、ユーザーやほかのプログラマのために書かれるものだ。
ふつう、ひとつのプログラムにつき、READMEファイルはひとつで、プレーンテキストファイルであることが多い。
![アメリカの中学生が学ぶドキュメント作成の授業【全世界700万人が感動したプログラミングノート】](https://dol.ismcdn.jp/mwimgs/b/9/400/img_b9616ad7dffaa2701c99a2119b2cdbca50354.png)
READMEファイルは、ユーザー情報を含むこともあるけれど、プログラムの使い方を説明するのには、ユーザーガイドを使うほうが一般的だ。
ユーザーガイドは、Microsoft WordやMicrosoft Excelのような巨大で複雑なプログラムに対してつくられる。
![アメリカの中学生が学ぶドキュメント作成の授業【全世界700万人が感動したプログラミングノート】](https://dol.ismcdn.jp/mwimgs/b/d/600/img_bd6224b618bfb0abc67b8bfaa47cc2a61509150.png)
![アメリカの中学生が学ぶドキュメント作成の授業【全世界700万人が感動したプログラミングノート】](https://dol.ismcdn.jp/mwimgs/b/2/600/img_b2cee4423ae3d3d47b220a0006366d9b99171.png)