1️⃣ コードをより詳細化するコメント(lower-level comment)
2️⃣ コードをより抽象化するコメント(higher-level comment)
どちらも必要なコメントとしつつ、本書では後者のコメントをより重視しています。
1️⃣ コードを詳細化するコメント(lower-level comment)
変数名などに残すタイプのコメントで、宣言した対象の単位や境界値、null許容などの詳細を明示することで、コードの正確性を高めます。こちらのタイプのコメントも必要ではあるが、命名でカバーできる範囲が広く必ずしもコメントが必要ではないタイプになります。コードの実装詳細の説明もこちらのタイプに属すると思います。
2️⃣ コードを抽象化するコメント(higher-level comment)
主にクラスやメソッドなどのインターフェイスに残すタイプのコメントで、コードの直感性を高めます。インターフェイスを切る作業はコードを抽象化する作業ですが、命名などで伝えきれない抽象化された内容を自然言語でコメントとして補足し、直感性を強化します。抽象化の精度について本書では、「メソッドの利用者がそのメソッドの実装詳細を読まないといけない状態は利用者のコードリーディング時間を無駄に生み出しており、インターフェイスの果たす役割である抽象化に失敗している」と述べています。もっともなことですが、個人的には普段各レイヤーを縦横無尽にコードジャンプして色んな実装詳細を結局読んでいるため耳が痛い話でした。
良い抽象化が行われているインターフェイスには必ずコメントが必要になります。 良い抽象化を「複雑な実装詳細が隠蔽されてシンプルなインターフェイスが提供されていること」であるとした時、その抽象化を説明する手段として「コード」だけを用いると具体的かつ詳細的になりすぎて説明が不足します。言い換えると、命名だけで支えられるインターフェイスは、その抽象化が弱いことを示していると言えるでしょう。
本書では、自然言語を利用できる「コメント」が最も抽象化を体現できる手段と捉えて、コードを書き始める前に先にコメントを書く「コメントファーストアプローチ」を採用することで、抽象化の具合を点検し、より良いシステムデザインを導くことができると主張しています。[...]