+ バートランドマイヤー氏のコメント論

コメントの書き方について、オブジェクト指向の大家、バートランドマイヤー氏が鋭いことを言っておられます。
何かにつけてコレを思い出そうとするのですが、細かい点を忘れてしまったりします。
そこで、ちょっとここに引用をさせていただき、日々の仕事で参考にさせていただきたいと思います。

（前略）

読む人にはそれなりの知識があるものと心得ておくべきである。近くにあるプログラムテキストから明らかな情報をヘッダコメントで繰り返す必要はない。例えば、次のように始まるルーチンのヘッダコメントは、

 tangent_to( c: CRICLE; p: POINT ) : LINE

次のように記述するのではなく、

 -- 点 p を通した円 c への tangent

単にこのように記述すべきである。

 -- p を通した c への tangent

なぜなら c が円（CIRCLE）で p が点（POINT）であることはファンクションヘッダから明らかだからである

無駄な言葉や言い回しを避ける。たとえば、ファンクションの目的を説明するための”...を返す”は無駄である。上の例では、”点(0, 0)からの距離を返す”や”...のタンジェントを返す”はなんら有益な情報を提供していない。読む人はファンクションが何かを返すことを知っているのである。もう１つの目障りな言い回しは、”このルーチンは...を計算する”とか、”このルーチンは...を実行する”といった表現である。次のように書く代わりに、

 -- このルーチンは利用者の最後の入力に従ってディスプレイを更新する

こう書くべきである

 -- 利用者の最後の入力に従ってディスプレイを更新

コメントを読むことになる人々に文学的趣味があるならば、諸君の書いたコメントよりはヘンリー・ジェームズを好んで読むだろう

一貫性を持たせること。あるクラスのファンクションのコメントに”文字列の長さ”という表現があったら、同じクラスのルーチンで同じ属性を対象とする場合に”文字列の幅を更新する”と書いてはならない

一般に、コメントはコードよりも抽象度が高くなければならない。ヘッダコメントの場合、アルゴリズムを”どのように使っているか（How）”よりも、ルーチンが”なんであるか（What）”についてだけ記述すべきである

（後略）