コメントに何を書くかで、後から読むときの楽さが変わる

• 何をしているかは、コードを読めば分かる
• 書くべきは、なぜそうしたか
• 意図が残っていると、直すときに迷わない

コメントを付けるようにしたが、最初は役に立たなかった。何を書くかを変えてから、意味が出てきた。

役に立たなかったコメント

最初に書いていたのは、こういうものだった。

• 「変数に値を入れる」
• 「ループを回す」
• 「関数を呼び出す」

どれもコードを読めば分かることだ。書く意味が無かった。

書くべきこと

いまは、こういうことを書いている。

• なぜこの方法を選んだか
• なぜこの値なのか
• 触ると何が起きるか
• 一見おかしく見える記述の理由

4つ目が最も価値がある。理由が分からないと、消してよいか判断できない。

数値の理由

特に、数値には理由を書いている。

• 「1600」— 文字数の下限。これ未満は広告枠を出さない
• 「760」— スマホとの境目。他の指定と揃えている
• 「3」— 試して、これ以上は守られなかった

3つ目のような理由は、書かないと完全に失われる。

避けた方法を書く

採用しなかった方法も、残すことがある。

• 別の方法を試したが、こういう理由でやめた
• 後から見た人が、同じ検討を繰り返さずに済む
• 自分が半年後に見るときにも効く

2つ目が目的だ。「これはもっと簡単に書けるのでは」と思って、同じ失敗をする。

頼むときの指定

コメントの内容も、指定するようにした。

各処理にコメントを付けてください。

- 何をしているかは書かない。コードを読めば分かる
- なぜその方法を選んだかを書く
- 特定の値を使う理由があれば書く
- 一見おかしく見える記述には、理由を添える

1つ目を明示しないと、処理の説明が並ぶ。

量の目安

多ければよいわけでもない。

• すべての行に付けると、かえって読みにくい
• まとまりごとに1つ
• 自明な部分には書かない

3つ目の判断が要る。コメントが多すぎると、重要なものが埋もれる。

自分の言葉で書く

生成されたコメントは、書き直すことがある。

• 一般的な説明になっていることがある
• 自分の判断は、自分で書く
• 理由は、こちらにしか分からない

3つ目が本質だ。なぜそうしたかは、決めた人しか書けない。

日付を入れる

変更を加えたときは、日付も書いている。

• いつ、なぜ変えたか
• 以前の状態に戻すべきか判断できる
• 古い記述を消すときの材料になる

3つ目が効く。2年前の対応が、いまも必要か判断できる。

ファイルの冒頭にも書く

個々の処理だけでなく、ファイル全体の説明も書いている。

• このファイルが何を担当するか
• どこから呼ばれるか
• 触るときの注意

2つ目があると、全体の構造が掴める。ファイルを開いた瞬間に、どの位置にあるものか分かる。引き継いだコードを読むとき、最も欲しかった情報がこれだった。自分が書く側になったときは、必ず入れるようにしている。

消すときの判断

コメントがあると、消す判断もできるようになった。

• 理由が書いてあり、その理由が消えていれば、消せる
• 理由が書いていなければ、残す
• 日付が古く、対象の環境が無くなっていれば、消せる

2つ目を原則にしている。理由が分からないものは、理由があると考える。コメントが無いことが、消せない理由になる。だからこそ、書くときに理由を残しておく価値がある。

コメントの保守

コードを変えたら、コメントも直している。

• 内容と合わないコメントは、無いより悪い
• 誤った説明を信じて、間違った判断をする
• 変更時に、必ず見直す

1つ目が実感だ。古いコメントに惑わされたことがある。

まとめ

• 何をしているかは、コードを読めば分かる
• なぜそうしたか、なぜその値かを書く
• 採用しなかった方法も、理由とともに残す
• すべての行に付けず、まとまりごとに1つ
• 内容と合わないコメントは、無いより悪い