Tidy First? ―個人で実践する経験主義的ソフトウェア設計

14章説明コメント

コードを読んでいて「なるほど、それでこうなっているのか」と声が出ることがある。これは貴重な瞬間だ。記録しよう。

コードからは読み取れないことを書いておく。未来の読み手や15分前の自分自身の立場に立ってみよう。何を知っておきたかっただろうか？ 「以下の処理が複雑なのは、ネットワーク呼び出しの回数をできる限り減らすためである」のようなメモかもしれない。

あなたとは違うタイプの人だとしても、特定の誰かに向けて書こう。自分がコンピューターサイエンティストのチームで唯一の生物学者だったら？ それなら、自分にとっては明白なことでも、コードに生物学の文脈で説明を入れておくほうがよい。第三者の観点から考えて、ありがちな疑問に先回りして回答しておくことが重要だ。

ヘッダーコメントがないようなファイルに出くわしたら、将来の読み手に向けて、なぜこのファイルを読むことが役に立つのかを伝えるヘッダーを追加することを検討してほしい（アラン・メルトナーに感謝†1）。

[†1] 訳注：ケント・ベックの有料記事へのフィードバックコメント。

欠陥を見つけた直後はコメントをするのに絶好のタイミングだ。たとえば、// 別のケースを追加する場合は必ず../fooも変更することとかだ。こういった結合があるのは理想的ではない。いずれ結合のなくし方を学ぶ必要が出てくるが、それまでは、砂に埋めるよりも結合の問題を指摘するコメントを追加しておくほうがはるかにマシだ。