コードとコメントの書き分け

大原則

情報には置き場所がある。置き場所を間違えた情報は、読み手が探しても見つからないか、古くなって嘘になる。

置き場所	書くこと	具体的には
コード	How	どうやって実現しているか
テストコード	What	何が起きるのが正しいか
コミットログ	Why	なぜこの変更が必要だったか
コードコメント	Why not	なぜ他のやり方を採らなかったか

コードコメントに置くのは「あえてやっていないこと」である。やっていることはコードが語るため、重ねて書くと二重管理になる。

出典: t_wada 氏の投稿（2017年9月5日, https://x.com/t_wada ）

コメントを書く前に

コメントを書きたくなったら、先にコードで表現できないかを試す。コードとコメントは別々に変更されるため、コメントは必ず古くなる。 コードで表現できる情報をコメントに置くと、いつか嘘になる。

1. 名前を変えて説明が要らなくならないか（code-naming スキル）
2. 処理をひとまとまりの関数に切り出して、関数名で説明できないか
3. 途中の式を、意味のある名前の変数に受けられないか
4. 定数に名前を付けられないか

ここまでやって消えなかった情報だけをコメントにする。

コードコメントに書くこと（Why not）

コードを読んでも分からず、かつその場所を触る人が必ず知る必要があることだけを書く。

• あえてやっていないこと。 一見すると足りない処理が、意図的に無いこと。
• 一見不自然な書き方をしている理由。 外部仕様の制約、既知の不具合の回避、性能のための妥協。
• 採用しなかった代替案と、採用しなかった理由。 後から「こう書けばいいのに」と思った人が、同じ検討をやり直さずに済む。
• 制約の出典。 公式ドキュメントの URL、Issue 番号、実測した結果。後から前提が変わったかを確認できるようにする。

書き方の目安。

// ここでリトライしないのは、呼び出し先が冪等でないため。
// 二重実行になるより、失敗を上位に返すほうが安全（Issue #123 の議論による）。

// 500 件ずつに分けているのは、SDK が 1 回あたり 500 件を超えると
// 例外を投げるため（公式ドキュメント https://example.com/docs/batch ）。

コードコメントに書かないこと

書かないもの	理由
コードをなぞる説明	コードを変えたときに必ず食い違う
変更履歴・作成日・作成者	バージョン管理が持っている情報
コメントアウトしたコード	消す。必要ならバージョン管理から戻せる
引数名を並べただけの定型的な説明	情報量がなく、読み飛ばす習慣を作る
これから直すつもりの内容（期限も担当も無いもの）	Issue にする。コードに残すと放置される

テストコード（What）

テストは仕様書として読まれる。テスト名だけを並べて読んだときに、その機能が何をするものか分かる状態にする。

• 名前に「どういう状態で」「何をすると」「どうなる」を入れる。
• 1つのテストで検証する結果は、読み手が1文で言える範囲に収める。
• テスト本体に How を書きすぎない。準備が長くなるなら補助関数に切り出し、テスト本体には検証したいことだけを残す。
• 期待値がなぜその値なのかが自明でないときだけ、コメントを添える。

test_deliver_notifications_outside_delivery_window_persists_nothing
test_delete_stale_push_tokens_deletes_only_tokens_older_than_400_days

コミットログ・PR（Why）

何を変えたかは差分が語る。なぜ変えたかは差分から読めない。

• コミットの表題は、その変更が何をするものかを1行で書く。
• 本文には、なぜその変更が必要だったか、どういう問題を解決するかを書く。
• 設計上の判断をしたなら、選んだ案と選ばなかった案、その理由を書く。
• 前提の出典（Issue、ドキュメント、実測結果）を添える。

設計文書の判断理由をどこに残すか

実装計画や設計文書は、実装後に更新されないまま古くなるか、役目を終えて削除される。そこにしか書かれていない判断理由は、いずれ失われる。

実装計画に判断理由が書かれている場合、どちらに移すかを決める。

理由の性質	移す先
その行・そのブロックを触る人が必ず知る必要がある	コードコメント
変更全体の背景であり、個々の行には紐づかない	コミットログ・PR 本文

どちらにも当てはまらない理由は、実装が終われば不要になったということなので、移さない。

書き上げたあとのチェック

• コードの内容をそのまま日本語にしただけのコメントが残っていないか
• コメントで説明している内容を、名前の変更や関数の切り出しで消せないか
• 「あえてやっていないこと」が、コメントとして書かれているか
• 制約や妥協の理由に、出典（URL・Issue 番号・実測結果）が付いているか
• コメントアウトされたコードが残っていないか
• 変更履歴や作成者をコメントに書いていないか
• テスト名だけを並べて読んで、仕様が分かるか
• コミットログ・PR 本文に「なぜ」が書かれているか（差分の言い換えで終わっていないか）
• 実装計画にしか書かれていない判断理由が残っていないか