前回
リーダブルコード 5 コメントすべきことを知る - by shigemk2
- 代名詞は避ける
- 関数の動作は出来るだけ簡潔に正確に説明する
// このファイルに含まれる行数を返す
function countlines($filename) { .. }
でも行数って何のことなのか、いまいちよく分からなかったりするよね。たとえば
Hello \n world
って1行なの?2行なの?という問題に、このコメントは答えていない。
というわけで、
// このファイルに含まれる改行文字('\n')の数を返す
function countlines($filename) { .. }
とするとより正確。
- コメントに含める入出力の実例を慎重に選ぶ(ただし、抽象的な説明より実例を選んだほうがよい)
- コードの意図は詳細レベルではなく高レベルで記述する
- よくわからない引数にはインラインコメントを使う
- コメントを簡潔に保つ
繰り返しになるけど、コードの動作をそのままコメントしても意味がない。
高レベルで、何をしているかを記述する必要がある。
// listをイテレートする for ($i = 0; $i < length($list); $i++)
// 価格の高い順に表示する for ($i = 0; $i < length($list); $i++)
みたいな。
パターンやイディオムを説明する言葉を探して、繰り返されている言葉を簡潔にすることを考えてみるとよい。
たとえばAvenueが何度も出てきたら、Ave.にするとか。
