UX / UI のデザインに強いWebシステムの開発と、BtoB Webマーケを支援するWeb制作を提供する
N's Creates (エヌズクリエイツ) 株式会社 フロントエンドエンジニアの齋藤 (@31mskz10) です。

「コメントなんて書かなくても、コードを読めば分かるだろう」
そう思ったことはありませんか？

確かに、コードを読めばその動作は理解できるかもしれません。
今回は、書籍『リーダブルコード』で語られる原則にも触れながら、コードにおけるコメントの本当の役割について考えていきます。

コメントの本当の役割

『リーダブルコード』では、コメントの目的は書き手の意図を読み手に伝えることだとされています。

優れたコメントは、コードが「何をしているか（What）」をなぞるのではなく、コードだけでは伝わらない「なぜ、そうしているか（Why）」を教えてくれます。

「なぜ」を伝えるコメント

コードが分かる人であれば、コードを読めば「何をしているか」は読み取れます。
しかし、なぜその処理が必要なのか、なぜ他の方法ではなくこの方法を選んだのか、といった「背景」や「理由」はコードだけでは伝わりません。

例えば、特定のブラウザが持つバグを回避するための少し変わったコードや、ビジネス上の特殊な要件を満たすための処理などです。
こうした「なぜ」がコメントとして残されていないと、将来コードを修正する人が「不要なコードだ」「リファクタリングすべきだ」と誤解して削除してしまい、バグを再発させる原因になります。

意図や前提を伝えるコメント

そのコードが動作するための前提条件や、将来的に修正が必要な点をメモとして残すことも、コメントの重要な役割です。

例えば、下記のようなコメントがあれば、他の人が今後の開発計画に役立てることができます。

// TODO: 現在はPNG形式のみ対応。将来的にはJPEGにも対応が必要

他にも、一見して意味の分からない定数（マジックナンバー）に対して、その数値が選ばれた背景を説明するコメントも価値があります。

// 最大再試行回数。サーバーの負荷を考慮して3回に設定

書くべきではないコメント

一方で、価値のないコメントは、コードの可読性をかえって下げてしまう「ノイズ」になります。

コードをそのまま説明するコメント

最も典型的な悪いコメントは、コードに書かれている内容を、そのまま文章にしただけのものです。

// iに1を足す
i = i + 1;

これはコードを読めば分かることで意味がありません。

分かりにくい名前を補うためのコメント

分かりにくい変数名や関数名を付けてしまい、それを補うためにコメントを書くのは本末転倒です。
まず名前そのものを改善すべきです。

// 顧客のセッションが有効かどうかをチェックする
if (check(t)) { ... } 

上記のようなコードは、コメントに頼るのではなく、下記のように名前を改善することで、コメントが不要になります。

if (isSessionActive(lastLoginTime)) { ... }

良い名前は、それ自体が最高のコメントになります。
命名は大事だなと改めて考えさせられます。

古くなった or 間違ったコメント

コードを修正した際に、コメントを修正し忘れると、コードとコメントの内容が食い違ってしまいます。

間違ったコメントが残っていると、それを読んだ人を深刻な混乱に陥れ、バグの原因にもなりかねません。
コメントは常に最新の状態に保つ必要があります。

理想は「コメントがなくても分かるコード」

もちろん、目指すべき理想は、コメントに頼らなくても意図が伝わる、自己説明的なコード（Self-Documenting Code）です。

分かりやすい変数名や関数をつけたり、ひとつの関数がひとつの役割だけを持つように設計したりすることで、多くの「何をしているか」を説明するコメントは不要になります。

しかし、先述したように、コードの背景にある「なぜ」は、どれだけコードを綺麗に書いても表現しきれません。
つまり、目指すべきは「自己説明的なコード」と、それを補完する「”なぜ”を伝える価値あるコメント」の両立です。

まとめ

「コメント」と聞くと単なる説明文のようなイメージを持ってしまいます。
どちらかというと「メッセージ」と考えると良いかもしれません。

また、作っている最中は夢中になって「後で読んでもコードを見れば分かるだろう」と思ってしまいますが、しばらく時間が経ってから改めて見ると「あれ……なんでこんな風に書いているんだっけ？」となってしまいます。

「初見の人が見ても分かるかどうか？」を考えてみるのが、本当に分かりやすいコードを書くための一歩になるのかもしれません。

---

UX / UI のデザインに強いWebシステムの開発と、BtoB Webマーケを支援するWeb制作を提供する
N's Creates 株式会社は、神戸三宮オフィスまで週１出社（それ以外はリモートワーク）できる「デザイナー」「エンジニア」を募集しています。

興味のある方は、カジュアル面談しますので気軽にお問い合わせください！