人月の神話第15章：人間がプログラムを理解できるようにドキュメントを書く

プログラムを書いた人自身にとってすらドキュメントは重要である。なぜなら、未来の自分はその詳細をたいてい忘れているからだ。
良いドキュメントを作る癖を付けさせるには、何よりもそのやり方を実際に見せることだ。怠惰や時間の無さを克服するための心構えを新人プログラマにたたき込むようなやり方は、概ね失敗に終わってきた。

ドキュメントに必要な記載内容
フローチャートはほとんど必要ない
ソースコードとドキュメントはなるべく1つのファイルにまとめる。
1. 1つのファイルにまとめる利点

ドキュメントに必要な記載内容

それぞれの記述項目の詳細は第15章の「What Documentation Is Required?」の項を参照のこと。

プログラムを使用するときに向けて

概要の記述が不足しないように気をつける。全体像から始めて詳細な説明に至る流れに気をつける。
書くべき記述項目は以下の9つ。用途目的、動作環境、入出力データの範囲、実現される機能と利用されているアルゴリズム、入出力の形式、操作方法（異常終了における挙動の説明も含める）、選択可能事項（options）、実行時間、計算精度とその確認手段
簡潔さと正確さに気をつける必要はあるが、これら9項目は大概3、4ページで記述できる。
これら9項目のドキュメントの大半はプログラムを書き始める前に草稿を用意するべきである。なぜなら、これらは、計画における基本的決定事項を具体化したものだからである。

プログラムが正常か確認するときに向けて

プログラムが壊れていないかや正しく動くかを確認できる小規模なテストケースがユーザーに提供されるべきである。
また、修正後に走らせる徹底的なテストも必要であり、これは主に3種類に分けられる。
1. 主要ケース（Mainline cases）：主要な機能を典型的なデータでテストするもの。
2. ぎりぎりで妥当なデータ：入力として認められているぎりぎりの値でプログラムが適切に機能するかテストするもの。テストに使う値は最大値や最小値、例外的な値ではあるが入力として認められている全ての値などである。
3. ぎりぎりで妥当でないデータ：入力として認められない値が来たときに、適切なエラーメッセージが表示されるかテストするもの

（回帰テストという言葉を著者は用いていないが、修正後に走らせる徹底的なテストは回帰テストと考えて良いだろう。また、2と3のテストは境界値テストと捉えても良いだろう。）

プログラムを変更するときに向けて

プログラムを変更したり修正したりするときには、内部構造を始めとしたプログラムの完全な詳細情報が必要となる。この中でも特に概観（overview）に関する情報が重要であり、これは以下の5つからなる。また、これらの情報は、コメント使ってソースコードに統合することが可能である。

フローチャートまたはサブプログラム構造図（フローチャートについては後述の点に注意。また、サブプログラム構造図がどのような図であるかは第15章の「The Flow-Chart Curse」の節とFig. 15.1を参照のこと。）
アルゴリズムの完全な説明、もしくは、それが記載されている文献の情報
ファイルレイアウトの説明
記憶デバイスなどからのデータ移動経路の構造の概観と各経路で何が完了するかの概観
元の設計の観点から考えた修正に関する議論、プログラムの起点（hooks）と終点（exits）の性質と位置、プログラムを最初に書いた人がどのような修正が望ましくそれをどのように行おうと考えていたかについての広範な議論、及び、隠れた危険についての所見

フローチャートはほとんど必要ない

フローチャートはまったくもって過大評価されている。多くのプログラムはフローチャートを全く必要としないし、必要があったとしても多くは1ページに収まるフローチャート1つで十分で、それ以上を必要とするプログラムはほとんど無い。
読み手に全体像を分かりやすく示す1枚の図が重要なのであって、フローチャートという形式にとらわれる必要は無い。ましてやフローチャートの規格や標準にある細かな規則は1枚の全体図を書くときには必要無い。
高級言語で開発するなら逐一の詳細を記したフローチャートは不要である。逐一のフローチャートは、歴史的には、アセンブラ言語での開発のために導入されたものである。体系だった高級言語で記述されたソースコードと比較して逐一のフローチャートが役立つのはGOTOの行き先を示す矢印ぐらいである。
プログラムを書く前に詳細なフローチャートを作成することが規則となっている現場で、経験豊かなプログラマが実際にそうするのを見たことがない。また、多くの現場で、ソースコードからフローチャートを生成するプログラムを使っている。こういうことは、恥ずかしいとか嘆かわしいとかいうよりも、良い判断が行われていると言うべきである。諸先輩方も私たち自身も達成できなかった時代遅れの慣行を新人プログラマに背負わせるべきではない。

ソースコードとドキュメントはなるべく1つのファイルにまとめる。

ソースコードに出てくる（変数名や関数名といった）名前は、最大限読み手に意味を伝えられるものにすること。
インデントを適切に行って従属関係や入れ子（nesting）を分かりやすくすること。
まとまった量の文章からなるコメント（paragraphs of comment）をソースコードにしっかり記述すること。組織が堅苦しい規則を設けている場合は特に、行単位のコメントが過多で、この文章からなるコメントが不足していることが多い。
どうなっているかよりも、何故そうなっているかを書くこと。目的が理解の鍵である。高級言語の構文でさえも目的を伝えることは出来ない。（第18章の15.14より）