昨年からゆっくり読み続けているA Philosophy of Software Designにコメントについての章があり、ふむふむと読んでいたのだけど、ひときわ目を引いたのがタイトルのような内容だった。

インターフェイスのコメント

• クラス、メソッド、フィールドなどについてのコメントで、javadocやYARDなど、言語によってフォーマットが定められていることがある。
• コードの利用者に向けて書かれる。メソッドの引数や返り値、例外、事前条件、副作用など。逆に言うと、利用者にとって知る必要がない内部の詳細については書くべきではない。

実装のコメント

• メソッド内に書かれたコメント。
• コードの読者に向けて書かれる。読者がコードを理解するのを手助けするのが目的となる。どのようにしているのか（How）ではなく、何をしているのか（What）や何故しているのか（Why）について書く。
• 短いメソッドだとインターフェイスのコメントだけで十分なことが多いが、長いメソッドではいくつかのブロックに対してコメントを書くことがある。

感想

コメントには二種類あるということはぼんやりと認識していたものの、利用者向けのコメントと読者向けのコメントを明確に区別して書くべきという主張は初めて目にした。

本書には一貫して認知負荷（=知る必要のあること）を減らすための工夫について書かれており、コメントというトピックについても一貫していた。より複雑なアプリケーションをより少ない認知負荷で開発していくためにはこうした細かい積み重ねが不可欠なので、自分も日頃からこのようなコメントを書くように意識していきたいし、コードレビューにおいてもこういった観点を持つように意識していきたい。