TL;DR
- コメントは実装の後ではなく、設計の一部として最初に書く。
- 先にコメントを書くと、良いコメントが書け、抽象化の問題に早く気づけ、コメントを書くのも楽しくなる。
内容
後から書くコメントの問題
多くの開発者は、コーディングが終わってからコメントを書こうとする。しかし後回しにすると、書く量が増えて面倒になり、ドキュメントのないコードが増える。また、設計から時間が経つと、設計したときの記憶が曖昧になる。コードを見ながらコメントを書くので、コードと同じことを書きがちになり、重要な情報が欠けたコメントになる。
コメントを最初に書く
コメントは最初に書く（write the comments first）。たとえば、新しいクラスを作るときは次の順で進める。
- クラスのインタフェースのコメントを書く
- 重要な public メソッドのインタフェースのコメントとシグネチャを書く。実装はまだ書かない
- 重要なインスタンス変数の宣言とコメントを書く
- メソッドを実装し、必要に応じてコメントを足す。途中でメソッドが必要になれば、実装の前にインタフェースのコメントとシグネチャを書く。インスタンス変数が必要になれば、宣言とコメントを書く。コメントに問題が見つかれば、その都度直す
こうするとコードとコメントが同時に完成する。利点は次の 3 つである。
良いコメントが書ける
設計中にコメントを書けば、重要な設計上の問題を記録しやすい。実装に気を取られず、メソッドの抽象化やインタフェースに集中できる。
システムの設計を改善できる
コメントは、抽象化を完全に伝える唯一の手段である。そして、優れた抽象化は優れたシステム設計の基本である。
コメントは炭鉱のカナリアのような役割を果たす。メソッドや変数に長いコメントが必要なら、抽象化がうまくいっていない。これは Hard to Describe というレッドフラグである。コメントは、インタフェースがシンプルかどうかの判断材料になる。必要な情報を伝えつつ、短くシンプルなコメントで済むなら、インタフェースもシンプルである。
インタフェースのコメントと実装を比べれば、モジュールが深いかどうかも判断できる。インタフェースのコメントで実装の主な機能をすべて説明する必要があるなら、そのモジュールは浅い。ただし、コメントが必要な情報を欠いていたり、理解しにくかったりすると判断できない。コメントを先に書けば、抽象化の問題に早い段階で気づける。
コメントを書くのが楽しくなる
コメントは、設計時の決定を記録し、確かめるためのものである。コメントをどれだけシンプルに書けるかは、設計がどれだけシンプルかを表す。設計力を測る材料になり、モチベーションにもなる。
コストは小さい
コードの半分がコメントだとしても、コメントを書く時間は開発時間全体の 5% にも満たない。後回しにしても、節約できる時間はわずかである。先にコメントを書くと、コードを書き始める前に抽象化が安定するので、コーディングの時間も節約できる。逆にコードを先に書くと、抽象化した部分が後から変わる可能性が高く、多くのコードを直すことになる。
キーワード
自分の理解
後からコメントを書くとコードと同じことを書きがちになるのは、第13章 Comments Should Describe Things that Aren't Obvious from the Codeに反する。
コメントが抽象化を伝える唯一の手段だという話は、コードで表現できない設計の情報（インタフェースの非形式的な情報）は多い、という第12章 Why Write Comments? The Four Excusesの話につながる。
設計の最初にコメントを書けば、実装の前にコメントを見直して、良いコメント、つまり良い設計に磨き上げられる。良いコメントとは、抽象化をうまく説明しているコメントである。良いコメントを書くには、変数やコードの本質を見極める必要がある。これを設計の最初に行えば、その場しのぎのコードを書かずに済む。
抽象化がうまくできている状態とは、深いモジュール、つまり強力な機能をシンプルなインタフェースで提供している状態のことだ。