コードにコメントを書く上でのポイント
コードにコメントを書く上でのポイント。 Pete Goodliffeさんの教えを要約してみた。
大切なこと
- ソースコード自体を最高レベルのコメントと考えて、コメントがなくても理解できるコードを書くこと。
- コードと同じように、「見直し」と「修正」を何度も繰り返しながら質を高めること。
コメントを書く上でのポイント
方法ではなく理由を説明する
処理の内容の説明ではなく、
なぜそのように書かれているのか？
という理由や、
最終的に何が達成されるのか？
を説明する。
// UserRegistryからのデータで、Registryオブジェクトを更新する。
ではなくて、
// 登録情報を後で参照できるようにキャッシュする。
と、 コードの意図 を説明する。 コメントを書くときは、どちらの種類のコメントを書こうとしている常にチェックする。
保守によってコードに手を加える場合でも、その修正によって
コードの存在理由が変化すること
は、
その実現方法を変更すること
に比べれば少ない。 コメントに理由を記述した場合のほうが、コメント自体の保守作業もずっと楽になる。
また、コメントには「特定の実装方法を選択した理由」を書くことも考えられる。 あるコードの実装方法として2通りの選択肢があって、その一報を採用した場合など、 その選択の根拠を説明するコメントなどがあると良い。
コードの内容を言い換えただけの説明は避ける
// iを1増やす i++;
コードの内容を単に繰り返すだけの説明は書かない。
コメントをコードの代用にしない
言語自体の機構で強制することが可能な制約
// この変数にxxxクラス以外からアクセスしてはならない
この条件を言語の具体的な構文で表現することを検討する。
自分がコードを説明するためのコメントをたくさん書いていることに気づいたら、 とりあえず作業をやめる。 そして、 先に解決する大きな問題がないか を考える。
役に立つコメントを書く
得意な要素や通常は予期しない処理
読み手にとって意外に思われる記述
コードを書いた本人でさえ忘れることが多いので、 あとになって「コメントを書いておいて良かった！」と実感できる。
正しい情報
コメントがコメントでないのはどんなとき？それは「ウソ」が書いてあるときです。 コメントが記されているコードを修正するときにとてもありがちなので注意する。
書く価値のあるコメント
混乱を招くようなコメント、ごく一部の人しか理解できないコメントを書かない。
明瞭である
あいまいな記述は禁物。 可能な限り具体的で明確な内容を書くようにする。
// とりあえず無限ループでもしときます
理解しやすい
読んで理解できるもの。 とくに略語等は読み手を混乱させることがある。
// 彼がSGGKかどうかの判定 // FPMPの威力を測定する
まとめ
- コメントは量より質！
- より少なく、良質のコメントを書くように努める。
- 理由を説明するコメントを書く。
- コメントをたくさん書くより、優れたコードを書くことに集中する。
