【コード哲学エッセイ】 コメントは 「説明」 じゃなく 「意図」 だ —— 未来の読者への手紙

コードの横に、コメントを書く。
そのとき、あなたは何を書いていますか？

「この関数は〇〇を取得して、△△に保存する」
「ここでループを回して、リストを加工している」

かつての僕は、そう書いていました。
コードが「何をしているか」を、言葉でなぞる。
丁寧なコメントだと思っていたのです。

でも、ある日、その「丁寧さ」が、未来の誰かを混乱させていることに気づきました。

「説明」 は、コードと二重に書くだけ

コードを読めば、「何をしているか」は分かります。
処理の流れは、コードそのものが語っている。
そこに、同じ内容を日本語で書き足すと、何が起きるか。

コードが変わったとき、コメントは忘れられる。

処理を追加した、分岐を変えた、ライブラリを差し替えた。
そのたびに、コメントは古いまま残り、コードと食い違う。
読んだ人は、「コードとコメント、どちらを信じればいいんだ？」と迷う。
「説明」のコメントは、いつの間にか「嘘」をつき始めるのです。

しかも、コードを読めば分かることを、わざわざコメントで繰り返す必要はない。
読む人は、コードを読む。
そのうえで、「ここは何をしているんだろう」ではなく、「なぜ、こう書いたんだろう」を知りたい場面のほうが、ずっと多いのです。

僕が「説明」型のコメントを手放そうと思ったのは、そんな気づきからでした。

「なぜ」 が書いてあって、救われた夜

転機は、自分が書いたコードを、半年後に必死で読み返していた夜のことです。

ある条件分岐が、直感と逆の動きをしていた。
「なんでここ、こうなってるんだ？」
コードだけを見ても、理由が思い出せない。
当時の仕様も、チケットも、もう手元にない。

そのとき、たった一行のコメントが目に入りました。
「〇〇の仕様上、△△のときだけ逆転させる必要がある（〇〇担当者確認済み）」

その一行で、当時の自分が「なぜ」そう書いたかが、はっきり蘇りました。
コードは「結果」しか残していなかった。
でも、コメントが「意図」を残してくれていた。
未来の僕は、その手紙を受け取って、救われたのです。

逆の経験もあります。
他人のコードを読んで、「この処理、なぜこうなってる？」と詰まったとき。
コメントには「〇〇を取得して××する」とだけ書いてあり、「なぜこの方法で？」がまったく残っていない。
結局、本人に聞くか、仕様書を掘り起こすか、コードの履歴を遡るか。
時間が何倍もかかりました。

そのとき、僕は思いました。
コメントに書くべきなのは、「何をしているか」じゃない。
「なぜ、そうしているか」なのだと。

コメントは、未来の読者への手紙

コメントは、未来の自分か、同じコードを開く誰かへ宛てた、短い手紙だと思うようになりました。

手紙に書くのは、結果の報告ではない。
「こうしました」ではなく、「こうした理由は、こうだったのです」。
選択の背景、妥協した理由、仕様や制約の都合。
コードには表れない、判断の意図を、数行で残す。

そう考えると、何を書くかがはっきりしてきます。

「何をしているか」は、コードが語る。
「なぜそうしているか」は、コメントが語る。
その役割を分けるだけで、コメントは、何年経っても「嘘」をつかず、読む人を助けてくれるのです。

意図を残す、という習慣

いま、僕はコメントを書く前に、ひとつだけ自分に問いかけます。

「半年後の僕が、あるいはこのコードを初めて開く誰かが、ここを読んだとき、『なぜ？』と思うとしたら、何だろう？」

その「なぜ？」に答える一文を、残す。
それだけを心がけています。

完璧なコメントを書こうとしなくていい。
長くなくていい。
ただ、「なぜこうしたか」が、未来の誰かに届くかどうか。
それだけを意識する。

コメントは「説明」ではありません。
未来の読者への、意図の手渡しなのです。

だから僕は、コードを書いたあと、ほんの少し手を止めて、コメント欄に「なぜ」を一言、添えるようにしています。
それが、エンジニアとしての僕の、未来への誠実さだと思っているから。

あわせて読みたい

▼ 名前の付け方に「約束」の視点を持ちたいときに

変数名や関数名を「説明」ではなく「約束」として扱う。
未来の自分を裏切らない命名の考え方です。

▼ コミットメッセージに「物語」を残したいときに

「fix bug」ではなく、なぜそうしたかを残す。
未来の自分へ宛てた、コミットログの書き方です。

▼ バグや不具合を「手紙」として読みたいときに

バグを責めるのではなく、システムが伝えようとしていることを読む。
デバッグの視点を変える話です。

ひとりごと

「説明」型のコメントを書いていた頃のコードを、今でも時々目にします。
そのたびに、「ここ、なぜだっけ……」と自分で詰まることがあります（笑）

「意図」を残すようにしてから、半年後の自分がだいぶ楽になりました。
みなさんのコメントが、未来の誰かの「なぜ」に、そっと答えてくれますように。