良いコードコメントとは何か？論文から学ぶコメントの書き方✍️

はじめに

コードを書くとき、「コメントはどこまで書くべきか」で迷うことはないでしょうか？🤔

• コメントは多い方が良いのか
• どんな内容を書くべきか

こういった疑問に対して、実際のコードを分析した研究があります。

本記事では、その論文をもとに「良いコメントとは何か」を整理します。

参考にした論文

How Good is Your Comment? A Study of Comments in Java Programs（ESEM
2011）

オープンソースのJavaプロジェクトを対象に、コメントの量や内容を分析した研究です。

論文から分かること 📊

コメントは多いが、質にばらつきがある

コードの約25〜35%がコメントですが、すべてが有用とは限りません。

コメントは主に2種類に分かれる 🧩

• コードの説明コメント
• TODOやメモなどの作業用コメント

特に後者は、一時的な情報で終わることも多く、長期的な価値は低い場合があります。

良いコメントとは ✨

「なぜ」を書く 🔑

コードを見れば「何をしているか」は分かりますが、「なぜそうしているか」は分かりません。

// API制限があるためバッチ処理にしている
processInBatches(items);

背景や制約を書く 🧠

// SEO要件によりタイトルは30文字以内
truncateTitle(title);

読み手の疑問を先回りする 💡

// 古いブラウザ対応のためこの処理が必要

悪いコメントの例 ⚠️

コードの説明だけ

// 配列をループする
for (let i = 0; i < arr.length; i++)

古くなったコメント

// 最大10件（実際は変更済み）

放置されたTODO

// TODO: あとで直す

実務での判断基準 🎯

このコードを初めて見る人が困るか？

• 困る → コメントを書く
• 困らない → 書かない

AI時代のコメントの考え方 🤖

ここまで「人間が読むためのコメント」について整理してきましたが、最近はAI（Copilot / ChatGPT / Devinなど）もコードを読む前提になってきています。

そのため、コメントの役割も少し変わりつつあります。

AIにとってのコメント

AIはコードだけでなく、コメントも含めて理解します。

👉 コメントはAIへの指示にもなる

AIに有効なコメントの特徴

意図が明確に書かれている

// 検索結果の精度を上げるため、部分一致ではなく完全一致でフィルタする

制約・ルールが明文化されている

// ユーザーは最大3回までリトライ可能

ドメイン知識が含まれている

// SEO上、タイトルには主要キーワードを必ず含める

補足：コメントは少ない方が良い？

ここまでコメントの重要性について書いてきましたが、「そもそもコードが分かりやすければコメントはいらないのでは？」という考え方もあります。

これはある意味正しく、変数名や関数名、構造が適切に設計されていれば、コード自体が仕様を表現できる状態が理想です。

ただし、それでも

• なぜその実装にしているのか
• なぜ他の方法を選ばなかったのか
• ドメイン特有の制約

といった部分は、コードだけでは伝わらないことが多いです。

そのため、

👉 コードで「なに」を、コメントで「なぜ」を表現する

という役割分担が重要だと考えています。

まとめ 📝

コメントは量ではなく質が重要です。

特に、

👉 「なぜ」を書くこと

これがコメントの価値を大きく高めます。

またこれからは、

• 人間の理解を助ける
• AIの理解・生成を助ける

という 2つの役割を持つようになります。

おわりに

コメントは単なる補足ではなく、システムの意図を残すインターフェースになってきているのかもしれません。
チームでコメントの書き方を揃えると、コードレビューや保守の効率も上がります。
もしルールが決まっていない場合は、一度見直してみるのもおすすめです🙌