TL;DR
- 既存のコードを変えるときも、「最小の変更は何か」ではなく、最初からその変更を考えて設計したかのような構造を目指す。
- コメントをコードの近くに置き、重複を避けるといったルールを守れば、少ないコストでコメントを最新に保てる。
内容
戦略的に変更する
保守や拡張のしやすいシステムを作るには、動くだけでは不十分である（第3章 Working Code Isn't Enough）。これは既存のコードを修正するときにも当てはまる。多くの開発者は、コードの変更が新しいバグを生むのを恐れるので、バグの修正や機能の追加のときに「これを実現する最小の変更は何か」と考えがちである。しかし、この考え方は戦術的プログラミングにつながる。最小の変更のたびに、特殊なケースや依存関係などの複雑さが加わり、設計が少しずつ悪くなる。
クリーンな設計を保つには、既存のコードを変えるときも戦略的プログラミングの姿勢をとる。変更が終わったときに、最初からその変更を考えて設計したかのようなシステム構造になっていることを目指す。そのために、変更を踏まえて今の設計が最善かを考え、最善でなければリファクタリングする（継続的な投資）。こうすれば、変更のたびに設計が良くなる。
コメントを最新に保つ
既存のコードを修正すると、コメントが不正確になることがある。次のルールを守れば、少ないコストでコメントを最新に保てる。
コメントはコードの近くに置く
コメントを対象のコードの近くに置けば、コードを更新するときにコメントも確実に更新される。
コードから離れたコメントほど抽象的にする
こうすると、コードの変更でコメントが意味を失う可能性が低くなる。たとえば、メソッドに主要な 3 つの段階があるときは、すべての段階の詳細をメソッドの先頭にまとめて書かない。各段階のコメントを、その段階の最初の行の直前に書く。ただし、メソッドの先頭に全体の流れを説明するコメントがあると役立つ場合もある。その場合も、詳細は各段階のコードの直前に書く。
// We proceed in three phases:
// Phase 1: Find feasible candidates
// Phase 2: Assign each candidate a score
// Phase 3: Choose the best, and remove itコメントはコミットメッセージではなくコードに書く
コミットメッセージに重要な情報があっても、開発者がそのログを探し出すのは手間である。コミットメッセージを書くときは、将来その情報を使う可能性があるかを自問し、あるならコードに書く。
コメントの重複を避ける
コメントが重複していると、開発者が関係する箇所をすべて見つけて更新するのが難しくなる（DRY）。設計上の決定は一度だけコメントする。たとえば、トリッキーな振る舞いをする変数が複数の場所で使われるときは、使う側のコードを理解しようとする開発者が最も確認しそうなのは変数の宣言なので、その振る舞いを宣言にコメントする。
適切な場所がない場合は、designNotes のようなファイルを作るか、使える場所のうち最良の場所に書く。後者の場合、他の場所には「このコードの説明は xyz のコメントを参照」と書いておく。参照先が移動や削除されれば、開発者は指示された場所でコメントを見つけられず、情報が古いことに気づける。一方、コメントが重複したまま更新されていなければ、情報が古いことを示す手がかりはない。
あるモジュールの設計上の決定を、別のモジュールで説明しない
たとえば、メソッドの呼び出し側には、呼び出したメソッドの中で何が起こるかを説明するコメントを書かない。知りたい読み手は、そのメソッドのインタフェースのコメントを見ればよい。IDE ではメソッドを選択したりマウスを重ねたりすれば、インタフェースのコメントが表示される。
プログラムの外ですでに文書化されている情報は書かない
代わりに、外部のドキュメントへの参照を書く。たとえば、HTTP を実装するクラスでは、コードの中で HTTP を説明せず、仕様の URL を書く。各コマンドを実装するメソッドがあり、ユーザマニュアルでコマンドが説明されているなら、インタフェースのコメントに「詳細はユーザマニュアルを参照」と書けばよい。
差分を確認する
コミットの前に数分かけて、git diff ですべての変更箇所を確認する。コメントが更新されているかに加えて、デバッグ用のコードが残っていないか、TODO を片付けたかも確かめる。
コメントを抽象的にする
コードの詳細を反映しない抽象的なコメントのほうが保守しやすい。一般に、コードを繰り返すだけでない有用なコメントは、保守も簡単である。ただし、詳細で正確なコメントが必要な場合もある。
キーワード
自分の理解
プログラムの外ですでに文書化されている情報をコメントに書いてしまうのは、Web の開発でよくある。これは意識していきたい。