ソースコード中のコメントを書く時の心得

ソースコードのコメントを書く時、直す時、レビューする時は、以下の基準に従う。

心得1. コードから読めない事だけを書く

コメントに書いてよいのは、コードを読んでも分からない事だけである。非自明な制約、invariant、隠れ仕様、gotcha、特定のbugへのworkaroundがこれに当たる。なぜそうするかという意図も書いてよい。

コードや配置から読み取れる事を、言葉でなぞらない。配置とは、ファイルの位置、関数名、周辺のコードの事である。自明な説明は実装との二重管理になり、コードを変更した時の更新漏れの原因になる。読み手には、コードと違う事を言っているかもしれないと疑う負担をかける。

• 直下の処理を言い直さない。text.replaceAll('\0', '') の直上に // NULを弾く と書かない
• 配置が既に表している前置きを書かない。特定の機能専用のディレクトリにある定数に「この機能専用の上限」と書かない。その場所に他の機能の上限があるはずがない
• 意図を書く前に、その動機がコードの式から読めないか確かめる。読めるなら書かない。書き残すなら、commit messageかPR概要欄に置く。メールの件名に (test ...) を付けるコードは、その式だけで、test送信を区別する意図が読める

書いてよいコメントの例を挙げる。

• // TextDecoderが既定でBOMを除去する
• // 上流APIの制約で、書き込みはPAT認証のみ
• // .trim()ではなく末尾改行のみ除去する。先頭空白は保持したい