10年前の
「地球の歩き方」
「この橋を渡れば安全です」と書いてある。
しかし、その記述は10年前のもので、目の前の橋は崩落していた。
古びたガイドブック（コメント）を信じた旅人（実装者）は、崖下に転落する。
- コードを修正した時、ついでにコメントを修正するのを忘れることが多い
- `// TODO: 後で直す` というコメントが3年以上残っている
- 「何をしているか」を説明するコメントばかりで、「なぜそうしたか」が書かれていない
- コメントと実装が矛盾していて、どちらが正しいか分からない
開発者はコードを読む時間よりも、コメントの真偽を疑う時間に人生を費やすことになります。
01. 親切心がアダになる
int tax = price * 1.10;
2019年、消費税率の変更時に担当者はコードを修正しました。
しかし、コメントの修正を忘れました。
数年後、このコードを見た新しい担当者は混乱します。
「コメントには8%とあるが、コードは10%だ。バグか？ それとも軽減税率の特殊ロジックか？」
調査に数時間を費やし、結局「ただのコメント修正漏れ」だと判明した時の徒労感。
メンテナンスされないコメントは、バグそのものよりもタチが悪いのです。
ないほうがマシだ。
02. コードで語れ
「Self-Documenting Code（自己文書化コード）」を目指しましょう。
変なコメントを書く必要があるということは、コード自体が難解である証拠です。
`// ユーザーが有効会員かチェック` というコメントを書く代わりに、
`isValidUser()` という関数を作るのです。
関数名を見れば、中身を見なくても何をするか分かります。
そしてコードが変われば関数名も変わるため、情報の乖離が起きにくくなります。
03. Whyを書け
では、コメントは一切不要なのでしょうか？
いいえ、「What（何をしているか）」ではなく「Why（なぜそうしたか）」を書くべきです。
「なぜこのアルゴリズムを選んだのか」「なぜあえて非推奨のメソッドを使っているのか」。
コード自体からは読み取れない「意図」や「歴史的経緯」こそが、
未来の担当者を助ける真のガイドブックとなります。