コメントに何を書くかで、後から読むときの楽さが変わる
処理の内容を書いても役に立ちませんでした。書くべきことを整理します。

この記事の結論
- 何をしているかは、コードを読めば分かる
- 書くべきは、なぜそうしたか
- 意図が残っていると、直すときに迷わない
- 何をしているかは、コードを読めば分かる
- 書くべきは、なぜそうしたか
- 意図が残っていると、直すときに迷わない
コメントを付けるようにしたが、最初は役に立たなかった。何を書くかを変えてから、意味が出てきた。
役に立たなかったコメント
最初に書いていたのは、こういうものだった。
- 「変数に値を入れる」
- 「ループを回す」
- 「関数を呼び出す」
どれもコードを読めば分かることだ。書く意味が無かった。
書くべきこと
いまは、こういうことを書いている。
- なぜこの方法を選んだか
- なぜこの値なのか
- 触ると何が起きるか
- 一見おかしく見える記述の理由
4つ目が最も価値がある。理由が分からないと、消してよいか判断できない。
数値の理由
特に、数値には理由を書いている。
- 「1600」— 文字数の下限。これ未満は広告枠を出さない
- 「760」— スマホとの境目。他の指定と揃えている
- 「3」— 試して、これ以上は守られなかった
3つ目のような理由は、書かないと完全に失われる。
避けた方法を書く
採用しなかった方法も、残すことがある。
- 別の方法を試したが、こういう理由でやめた
- 後から見た人が、同じ検討を繰り返さずに済む
- 自分が半年後に見るときにも効く
2つ目が目的だ。「これはもっと簡単に書けるのでは」と思って、同じ失敗をする。
頼むときの指定
コメントの内容も、指定するようにした。
各処理にコメントを付けてください。
- 何をしているかは書かない。コードを読めば分かる
- なぜその方法を選んだかを書く
- 特定の値を使う理由があれば書く
- 一見おかしく見える記述には、理由を添える1つ目を明示しないと、処理の説明が並ぶ。
そのまま使える形
コメントに書くのは何をしているかではない。コードを読めば分かる。書くのは次の4つ。
- なぜこの方法にしたか — 他の選択肢を落とした理由
- 触ると壊れる理由 — 「ここを消すと◯◯が動かなくなる」
- 一見おかしく見える理由 — 回避策や、外部の都合に合わせた箇所
- いつ見直すか — 「◯◯の対応が終わったら不要」
とくに3番。変に見えるコードは、後から来た人が「整理」して壊す。理由が書いてあれば止まる。
量の目安
多ければよいわけでもない。
- すべての行に付けると、かえって読みにくい
- まとまりごとに1つ
- 自明な部分には書かない
3つ目の判断が要る。コメントが多すぎると、重要なものが埋もれる。
自分の言葉で書く
生成されたコメントは、書き直すことがある。
- 一般的な説明になっていることがある
- 自分の判断は、自分で書く
- 理由は、こちらにしか分からない
3つ目が本質だ。なぜそうしたかは、決めた人しか書けない。
日付を入れる
変更を加えたときは、日付も書いている。
- いつ、なぜ変えたか
- 以前の状態に戻すべきか判断できる
- 古い記述を消すときの材料になる
3つ目が効く。2年前の対応が、いまも必要か判断できる。
ファイルの冒頭にも書く
個々の処理だけでなく、ファイル全体の説明も書いている。
- このファイルが何を担当するか
- どこから呼ばれるか
- 触るときの注意
2つ目があると、全体の構造が掴める。ファイルを開いた瞬間に、どの位置にあるものか分かる。引き継いだコードを読むとき、最も欲しかった情報がこれだった。自分が書く側になったときは、必ず入れるようにしている。
消すときの判断
コメントがあると、消す判断もできるようになった。
- 理由が書いてあり、その理由が消えていれば、消せる
- 理由が書いていなければ、残す
- 日付が古く、対象の環境が無くなっていれば、消せる
2つ目を原則にしている。理由が分からないものは、理由があると考える。コメントが無いことが、消せない理由になる。だからこそ、書くときに理由を残しておく価値がある。
コメントの保守
コードを変えたら、コメントも直している。
- 内容と合わないコメントは、無いより悪い
- 誤った説明を信じて、間違った判断をする
- 変更時に、必ず見直す
1つ目が実感だ。古いコメントに惑わされたことがある。
あわせて読む
- 読めないコードを書かせないために、頼み方を変えた — 短く書かれると読めません。自分が読める範囲で書いてもらう話です。
- 他人が書いたコードを読むとき、AIに説明させながら進める — 引き継いだサイトのコードが読めませんでした。全体から降りていく順番の話です。
- 色やサイズを変数にしたら、後から変えるのが楽になった — 同じ値を何か所にも書いていました。まとめた後の違いを書きます。
まとめ
- 何をしているかは、コードを読めば分かる
- なぜそうしたか、なぜその値かを書く
- 採用しなかった方法も、理由とともに残す
- すべての行に付けず、まとまりごとに1つ
- 内容と合わないコメントは、無いより悪い
新しい記事が出たら、ブラウザの通知でお知らせします。
メールアドレスの登録は要りません。いつでも止められます。
関連記事
RELATED
圧縮できるのは、冗長度があるから。情報の量の測り方を図にした
情報の量は意味では測りません。どれだけ絞り込めたかで測ります。1948年の論文が置いた定義と、英語の冗長度が約50%とい…
HOKKAIDO AI LAB を英語でも読めるようにしました。ボタン1つで翻訳、英語のページを作らなかった理由も
海外から読んでくださる方のために、ヘッダーに英語の翻訳ボタンを付けました。押すと、いま見ているページがその場で英語になり…
相席か個室か。1つの仕組みを何社で使うかを図にした
共有するか分けるかは0か1ではありません。層ごとに決められます。4つの構成と、それぞれで何を引き受けることになるのかを整…