by shigemk2

当面は技術的なことしか書かない

リーダブルコード 6 コメントは正確で簡潔に

前回
リーダブルコード 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.にするとか。