コメントを書く。

コードコンプリートによると、コメントには次の 5 種類がある。

すなわち、

1. コードの反復

コードのしていることを違う言葉で再表現したもの。

読み手の読む量を増やすだけで、何ら価値がない。

2. コードの説明

複雑なコード、トリッキーなコードを説明するもの。

多くの場合、コメントをつけるよりコードを改良 したほうが良い。

3. コードの目印 (マーカー)

開発者が作業途中であることを示すためにつけるもの。

4. コードのまとめ

何行かのコードをまとめて一つか二つのセンテンスにする。

こうしたコメントは単なるコードの反復のコメントより有益である。

なぜなら、コードの走査を迅速にできるからである。

まとめのコメントは、コードの原作者以外の人がコード変更をしようとするときに、とくに役に立つ。

5. コードの意図の記述

意図を表すコメントは、コードの目的を説明するものである。

意図コメントは、解法レベルよりも問題レベルの側に立ったものである。

例えば、/* get current employee information */ は意図コメントであり、一方 /* update EmpRec Structure */ は解法レベルでのまとめのコメントである。

以上のうち 2 種類のコメントだけが完成されたコードに許されている。

それは、意図コメントとまとめコメントである。