アメリカの中学生が学ぶドキュメント作成の授業【全世界700万人が感動したプログラミングノート】

2016年の発売直後から大きな話題を呼び、中国・ドイツ・韓国・ブラジル・ロシア・ベトナムなど世界各国にも広がった「学び直し本」の圧倒的ロングセラーシリーズ「Big Fat Notebook」の日本版が刊行された。藤原和博氏（朝礼だけの学校 校長）「プログラミングは新しい言語の獲得だ」、野田クリスタル氏（お笑い芸人・マヂカルラブリー）「プログラミングがやりたくなる！ まるでゲームの攻略本みたい！」、尾原和啓氏（元グーグル・IT評論家）「プログラミングを通して、ビジネスにも応用できる考え方が見えてくる！」と絶賛されている。本記事では、全世界700万人が感動した同シリーズのプログラミング編『アメリカの中学生が学んでいる 14歳からのプログラミング』より、本文の一部を抜粋・掲載します。

ドキュメントを作成する

　ドキュメント（文書）とは、プログラムのコードについて書かれた情報のこと。ドキュメントには主に、コメントとREADME（リードミーファイル）の2種類がある。

コメント

　どのプログラミング言語にも、コード内にコメントを追加する方法が用意されている。でも、コメントはプログラムの一部じゃないから、プログラムを実行するときには飛ばされるし、ユーザーの目には見えない。

　コメントは、プログラマがそのプログラムのコードについて書き残したメッセージなのだ。あるコードの果たす機能についての説明のこともあるし、追加または変更すべき内容についてのメモのこともある。

　あとでそのコードをチェックするプログラマへの質問を書き残す場合もあるのだ。

　コードにコメントを書き残すと、ある部分のコードがどんな機能を果たすのか覚えておくのに役立つ。特に、巨大なプログラムの場合は便利だ。なぜならどのコードがどう動作するのか、ぜんぶ丸暗記しておかなくてもすむから。

　でも、コメントは、短いプログラムでも役立つ。コードを書き終えたずっとあとになって、またそのコードを調べたくなることもあるからだ。

　それから、別のプログラムのコードや、きみやだれかが前に書いたコードを再利用したくなることもある。

　そんなとき、コメントがついていれば、きみが再利用したいコードをパッと見つけられる。

　たとえば、ゲームをつくっているなら、キャラクターを動き回らせるためのコードをきみ自身でつくる代わりに、別のプログラムからコピーすればすむ。

　きみのプログラムのなかで、どの部分がキャラクターを動かすためのコードなのかがわかるようにコメントを書き残しておくと便利だろう。

　コメントは、プログラムのデバッグにも役立つ。

　コメント部分は、プログラムを実行するときには飛ばされるから、バグがひそんでいるかもしれないコードをいきなり削除するんじゃなく、いったんコメントアウトするほうがいい。

　コメントアウトされたコードは、実行されないから、そこにバグが存在したかどうかがわかるというわけだ。

　また、コメントは、テストコードを追加して、デバッグをおこなうのにも役立つ。

　テストが終わったら、追加した部分をコメントアウトするだけで元に戻せるからだ。

　コメントは、きみ自身へのメモを残すのにも使える。

　たとえば、次のような表記を使って、きみ自身への短いメモを残すといいだろう。

　#BUGまたは#FIXME―あとで修正しようと思っているバグ。

　#TODO―本当は書かなくちゃいけないけど、後回しにしているコードについてのメモ。

README（リードミー）

　README（目立つよう、すべて大文字で書くのがふつう）とは、あるプログラムに関する情報が書かれたファイルのこと。

　たとえば、プログラムに含まれるファイルの一覧、インストール方法、使い方、著作権情報、判明しているバグなどを書くことが多い。

　READMEファイルは、ユーザーやほかのプログラマのために書かれるものだ。

　ふつう、ひとつのプログラムにつき、READMEファイルはひとつで、プレーンテキストファイルであることが多い。

　READMEファイルは、ユーザー情報を含むこともあるけれど、プログラムの使い方を説明するのには、ユーザーガイドを使うほうが一般的だ。

　ユーザーガイドは、Microsoft WordやMicrosoft Excelのような巨大で複雑なプログラムに対してつくられる。