✍️
なんでコメントって書くん？

2025/09/24に公開
みなさん、こんにちは！
claude code にハマってましたが、最近は codex に惹かれつつあるフロントエンドエンジニアの @nyaomaru です！
普段、コーディングをするときにコメントを書いたり書かなかったりすると思いますが、
「そもそも、なんでコメントって書かないといけないの？」
って疑問に思い、「AI 時代においてコメントは本当に必要なのかな？」って考えてみたので、記事にしてみました！
僕が最近愛読している A PHILOSOPHY OF SOFTWARE DESIGN (by JOHN OUSTERHOUT) の 12 章の記述をベースに考えてみたいと思います。
ほんなら、一緒に見てこな！

 📝 コメントとは？コード上に書くメモのことやな。
やけど、単なるメモやないで！
Good comments make a huge difference in the maintainability of software, so the effort spent on them will pay for itself quickly.
— JOHN OUSTERHOUT（12.2 I don't habe time to write comments, P.97）[1]
適切なコメントはソフトウェアの保守性に大きな違いをもたらすため、コメントに費やした労力はすぐに回収されます。
ってあるように、コメントはソフトウェアの運用保守において、とても重要な働きをするねん。
例えば、
const purchaseUsjTicket = async (visitDate: string): Promise<Ticket> => {
  // ...
  return ticket;
};
という関数があったとするで～。
関数名を読んだら何となくわかると思うけど、
/**
 * USJ（大阪）の指定日のチケットを公式手続きで事前購入します。
 * 背景: 当日の手続き時間を短縮するために購入フローを自動化。
 */
const purchaseUsjTicket = async (visitDate: string): Promise<Ticket> => {
  // ...
  return ticket;
};
ってコメントがあると、これ読んだら
「あ～、ユニバのチケット取る関数か。入口のとこで並ばなくてええなんて、便利やん？」
ってなるやん？やから、実装の詳細を読まなくても実装が適度に抽象化されて、理解しやすくなってるねん
つまり、ソフトウェアエンジニアにおけるコメントは、本の注釈みたいなもんやな

 どんな種類がある？一重にコメント言うても、いろんな種類があるで～


種類
優先度
ポイント


意図・背景のコメント
✅ Must
実装の Why を残す

仕様/契約 (JSDoc 等)
✅ Must
型や契約を明示

タグ付き (TODO 等)
💡 Nice to have
grep や管理に便利

ディレクティブコメント
⚠️ Conditional
使うなら理由を必ず書く

参照リンクコメント
💡 Nice to have
Issue/PR の背景を追える

他にもあると思うけど、実務でよく出てくるのはこの辺なんちゃうかな。
全部書けばええっちゅうもんやなくて、場合によっては書いたり書かなくても良かったりする。
その中でも、Why / 仕様 のコメント は極力書いたほうがええで～。
それぞれ見ていこか。

 ✅ 意図・背景のコメント（Why）基本的には なんでこれ作ったんか？ が書いてあると、将来の自分にも他の開発者にも優しいで～。
例えば、
const getExpoCongestedTime = (targetDate: Date): Promise<Time[]> => {
  // ...
  return congestedTimeList;
};
って関数があるとするやん？
これは、今の現在軸で読むと、
「あ～、たぶん 2025 年の大阪万博の混雑時間を取得する関数やな」
ってなると思うねん。
やけど、これが 5 年後、10 年後のシステムに残ってしまって、その時の開発者がパッとみたときに、
「あれ、そういえば万博って 1970 年と 2025 年にあったよな。でもいまだにこの関数が残ってるってことは、多分、なんかの統計を取るとかの要件で実装したんちゃうかな？じゃあ、これは日付を指定したらいいんやし、1970 年の分も指定したら取れるんかいな？実装見ても、条件分岐とかないし、ほんならとりあえず試してみよ。あれ？とれへんな。バグか？それとも仕様か？どっちや！？」
…ちょっと大げさかもしれへんけど、こうなるかもやん？？
これがさ、
/**
 * 万博の混雑時間を取得します。
 * 背景: 2025年大阪万博で利用したかったため作成。後続で削除予定
 */
const getExpoCongestedTime = (targetDate: Date): Promise<Time[]> => {
  // ...
  return congestedTimeList;
};
ってコメントあると、
「あ～、2025 年大阪万博の混雑時間を取得する関数かいな。運用保守で消し忘れてるやん。リファクタついでに消したろ～」
って、特に深くコードを読む必要もなく、消す意思決定ができるねんな。(実際に消すときには、念のためコードちゃんと読んだほうがええで！)
これはな、AI 使ってても一緒やねん。
いくらコンテキスト読み込ませて、どういう実装か要約してもらっても、背景までは読み取れへん。
「なんで？」
を正確に捉えるには、その時の考えや気持ちに思いをはせる能力が必要になってくる。
これは現状が正しいかどうか、だけで判別できひんから困ったもんやな。実際に動いてそうやったら簡単に消されへんし、結局コードを深くよんで仕様を理解する時間がかかる。
つまり、なんで？のコメントを書かないことによる技術的負債が生まれる可能性がある、ってことやな。
やから、みんな Why のコメント書こな～！🚀

 ✅ 仕様/契約のコメント (JsDoc/TSDoc)関数が持っている性質や仕様、契約についてのコメントで、具体的には JSDoc / TsDoc の記述形式の @param / @returns / @example とかのことやな。
/**
 * 万博の混雑時間を取得します。
 * 背景: 2025年大阪万博で利用したかったため。後続で削除予定
 *
 * @param targetDate 混雑時間取得対象の日付
 * @return 混雑時間の配列
 */
const getExpoCongestedTime = (targetDate: Date): Promise<Time[]> => {
  // ...
  return congestedTimeList;
};
このように、interface としての仕様が書いてあると、利用者側はパッと見で渡すもん＆何が返ってくるかわかるから、めっっっちゃ使いやすい！
特に日本語を native にしているから、翻訳するのにも認知負荷がかかるわけで、それが軽減されるだけでも価値ある。
全部に書いてなくてもええけど、utils や lib は汎用的に使ってもらいたいからこそ、誰もが使いやすいようにコメント書いてあると、みんなハッピーセットやな！
個人的には、What とセットやと、「何か」と「なぜ」が一緒に理解できて捗ると思ってるで～！

 💡 タグ付きのコメント「リーダブルコード」読んだことある人多いと思うけど、 TODO / FIXME / HACK / NOTE などが実務ではよく見るコメントやな。
それぞれに意味があって、ざっくりいうと
TODO: 後で改善予定の箇所
FIXME: 既知の問題や暫定対応
HACK: 本来望ましくないが必要なコード
NOTE: 設計上の理由や参考情報
って感じや。この semantic なコメントがあることで、読み手は「お。これは何か特殊な意味があるんだな」って目印になり、理解が捗るっちゅう優れもんや。
/**
 * 万博の混雑時間を取得します。
 * 背景: 2025年大阪万博で利用したかったため。
 * TODO: 後続で削除予定
 *
 * @param targetDate 混雑時間取得対象の日付
 * @return 混雑時間の配列
 */
const getExpoCongestedTime = (targetDate: Date): Promise<Time[]> => {
  // ...
  return congestedTimeList;
};
って書いてあると、grep しやすいし、VSCode の Todo Treeなんかの拡張機能を入れておくと、可視化されて見やすいねんな。
何か意図が含まれている実装には、タグ付きのコメントを書くと、将来の読み手に優しいわな～

 ⚠️ ディレクティブコメントeslint-disable や @ts-ignore など、コンパイルを助長したり制御するコメントやな。
現場やと
// eslint-disable-next-line no-unused-vars
const debugMode = true; // FIXME: 今は使ってないけど将来のために残してる

// HACK: 過去に実装された型が不明だから利用している関数
// eslint-disable-next-line @typescript-eslint/no-explicit-any
function handleLegacyData(data: any) {
  // @ts-ignore: 外部ライブラリの型定義が古いので一時的に無視
  someLegacyLibrary.doSomething(data);
}
みたいに、「しゃあない」部分に対して使うコメントやな。
このコメント自体に深い意味はないんやけど、error を抑止しているんだな～ってことはわかる。
本来は使わんほうがええコメントやけど、実際問題として使うこともあるわな。
そのときに、 なんで抑止してるんか？ もセットで書いてあると、他の人が実装を見たときに「なるほどな～」ってなるで～！
無効化するなら必ず理由を書こな！

 💡 参照リンクコメントIssue や PR、仕様書 URL などを参照するためのコメントやな。実務でよくあるんは
/**
 * build 時に実行する処理
 *
 * この関数は以下の issue を解消するために利用している
 * @see https://github.com/nyaomaru
 */
const specialFunction = () => {
  // ...
};
みたいに、issue や PR、notion の link などの、外部参照を行うためのコメントやな。
これがあると、「なんでこんな実装してるん？」の詳細が追えるから、めっちゃありがたい。

 なぜ開発者はコメントを書かないのか？ここまで書いてある内容を読むと、
「えっ、コメント書かない理由なくない？」
って思うかもしれんけど、実際の現場でコメントが書いてある箇所は限定的やったり、下手したらほとんどなかったりする。
開発者の言い訳としては、以下が挙げられる。
"Good code is self-documenting"
"I don't have time to write comments"
"Comments get out of date and become misleading"
"The comments I have seen are all worthless; why bother?"
— JOHN OUSTERHOUT（12 Why Write Comments? The Four Excuses, P.95）[1:1]
日本語に訳すと、
良いコードはそれ自体がドキュメントだ
コメントを書くための時間がない
コメントが古くなると誤解を招く
価値のあるコメントを見たことがない、なんでわざわざ？
って感じやな。Clean Code を読むと、コメントは害悪みたいな印象あるけど、良いコード + 良いコメント のほうが最強やで～。
ほな、一個ずつ見ていこか。

 良いコードはそれ自体がドキュメントだClean Code で言われてるやつやな。
確かに、正しい命名、型定義、処理が完結であれば中身を読めば理解できる。
でもそれはあくまでも良いコードが前提なわけで、もし良いコードでなければ、シンプルに意味わからん。
しかも、良いコードであったとしても、実装の背景までは読み取れへん
良いコードはええ。でも、コメントを書かない理由にはならへんわな。

 コメントを書くための時間がない実際、コメントを書くための時間は、開発の 10 % にも満たへん。
コメントから実装するわけじゃなく、実装からコメントを書くわけや。
しかも、出来立てほやほやなコードは、頭の中に仕様が入っとるから、コメントしやすいはずや。
でも、これをサボってまうと、あとで思い返すのに時間かかるし、他の人の時間を奪うことにもなる。
今や、AI がシュッとコメントのドラフト書いてくれるから、それに仕様や背景を追記するだけでええ。そんなに手間やないはずや。

 コメントが古くなると誤解を招くコメントと実装が乖離することで誤解を招く可能性は確かにある。
でも、コメントもコードの一部やと考えると、コードを修正するときにコメントを直さないわけがないわな。
しかも、AI に依頼すれば property や説明文はシュッと直るで。
CLAUDE.md や AGENTS.md に「コメント書いてな～」って書いておくと捗るし、Copilot の custom command を使うのもええで～！

 価値のあるコメントを見たことがない、なんでわざわざ？this is probably the one with the most merit.
— JOHN OUSTERHOUT（12.4 All the comments I have seen are worthless, P.98）[1:2]
おそらくこれが最もメリットのあるものです。
このコメントこそが逆説的な答えになっていて、すべての開発者は基本的にコードを読むときにコメントを読んでいる。 だからこそ、「価値のあるコメントを見たことがない」といった批判が生まれているわけやな。
価値のあるコメントが書いてないことは悪いことや。
だからこそ、価値のあるコメント書いていくことが大切になる。

 まとめ今回、なんでコメント書かなあかんのか？を、コメントの種類と書かない言い訳から考えてみた。
なんでコメントを書くのか？
それは 「機械が無視し、人間と AI の理解を助ける注釈」 のためや。
AI がコードを要約してくれても、「なぜこの仕様なのか」までは書いてくれない。AI 時代だからこそコメントの価値が高まってるんや。
人間の設計を正しく AI に伝えるために、AGENTS.md や CLAUDE.md を書くのは正しい。けど結局は既存の文脈にも大きく影響を受ける。やからこそ、細かい仕様や実装の背景のコメントを書いておくことで、AI に正しい実装をしてもらえる確率が上がる。
せやから、今の時代もコメントを書く必要があるんやな～。
ワイよ、ちゃんとコメント書こな。
ほんで、みんなもな 😹

 あとがき具体例として関数のコメントを扱ってきたけど、もちろん関数やクラスの中でコメント書くのも大事やで～！

 次回予告ほな、どんなコメント書いたらええねん？ ってモヤモヤしてる人も多いやろうから、次回の記事で触れていくで～！
期待せんと待っててな！
新作できたから見てってなぁ～！🚀
https://zenn.dev/nyaomaru/articles/how-can-i-write-comment

 引用元
脚注
JOHN OUSTERHOUT「A PHILOSOPHY OF SOFTWARE DESIGN」Yaknyam Press, Palo Alto, CA., https://www.google.com/url?sa=t&rct=j&q=&esrc=s&source=web&cd=&ved=2ahUKEwi7o9PBicSPAxUsslYBHVkqFvoQFnoECCsQAQ&url=https%3A%2F%2Fwww.amazon.co.jp%2FPhilosophy-Software-Design-John-Ousterhout%2Fdp%2F1732102201&usg=AOvVaw2GVzba-cqAlczi1R8Ju4aR&opi=89978449, 参照日: 2025-09-22 ↩︎ ↩︎ ↩︎
種類	優先度	ポイント
意図・背景のコメント	✅ Must	実装の Why を残す
仕様/契約 (JSDoc 等)	✅ Must	型や契約を明示
タグ付き (TODO 等)	💡 Nice to have	grep や管理に便利
ディレクティブコメント	⚠️ Conditional	使うなら理由を必ず書く
参照リンクコメント	💡 Nice to have	Issue/PR の背景を追える
📝 コメントとは？

どんな種類がある？

✅ 意図・背景のコメント（Why）

✅ 仕様/契約のコメント (JsDoc/TSDoc)

💡 タグ付きのコメント

⚠️ ディレクティブコメント

💡 参照リンクコメント

なぜ開発者はコメントを書かないのか？

良いコードはそれ自体がドキュメントだ

コメントを書くための時間がない

コメントが古くなると誤解を招く

価値のあるコメントを見たことがない、なんでわざわざ？

まとめ

あとがき

次回予告

引用元

Discussion
