こんにちは、decoponです。
私は新人の頃、先輩から「ちゃんとコメントを書いておいてね」と言われて戸惑いました。
書くって……何を？どこに？どのくらい？
当たり前すぎる説明は邪魔になるって聞いたし……
でも何も書かないと不親切だよね……？
そんなふうに、「コメントって、何をどう書けばいいの？」 とずっとモヤモヤしていました。
でも少しずつ、“書かれていて助かるコメント”と“意味がないコメント”の違いが分かってきて、
今では自分のコードにも他人のコードにも「これは読みやすい」と感じるポイントが見えてきました。
この記事では、コメントに悩んだ私が
「読み返したくなるコード」を意識するようになるまでの過程と工夫をまとめてみます。
🧠 第1章：コメントって、何のために書くの？
「コメント、ちゃんと書いてね」
――現場でよく言われる言葉ですが、最初はその意味がよく分かりませんでした。
・書くのってルールだから？
・誰に向けて？
・何を書いたら“ちゃんと”なの？
そう思いつつ、「とりあえず書いてあると安心でしょ」とばかりに処理の内容をそのまま日本語にしただけのコメントをつけていました。
🎯 コメントの目的は“未来の読者”のためにある
コメントの役割を考えたとき、私の中で大きく3つに分けられると感じました。
1. 処理の“意図”や“背景”を補足する
→ なぜこういう書き方をしたのか／例外対応が必要だった理由 など
2. コードから読み取りづらい“業務的な文脈”を伝える
→ 業務システムの仕様変更や例外フローなど、ドメイン知識に由来する前提の共有
3. 未来の自分や他の人が“安心して直せる”材料を残す
→ 「このコードを変えてもいいか」の判断に役立つヒントになる
🤝 “説明しなくても分かる”は、チームと時間が変わると危うい
今なら分かるのですが、
「見れば分かるでしょ」は、本人にしか分からない場合もあります。
・3ヶ月後の自分
・チームに新しく入った人
・1年後にバグ調査に来た別チームの人
そんな人たちが 「あ、これはこういう意図なんだな」と納得できる こと。
それこそが、いいコメントの大事な要素なんだと、私は徐々に気づいていきました。
😅 第2章：私がやっていた「意味がなかったコメント」
コメントを書こうと思っても、最初は「とりあえず何か書かなきゃ…」という焦りから、
“書いてあるけど、実は意味がなかったコメント” を量産していました。
ここでは、当時の私がよくやっていた残念コメントと、
なぜそれがよくなかったのかを振り返ってみます。
❌ 例1：そのまま日本語にしただけのコメント
// 変数xを初期化
let x = 0;
// ユーザー一覧を取得
getUserList();
✅ コードを見れば一目瞭然。“見れば分かること”しか書いていないコメントは、 むしろ「読みづらさ」を増やしてしまうことも。
❌ 例2：「処理内容だけ」をあいまいに書く
// エラー処理
try {
...
} catch (e) {
...
}
✅ どういうエラーを、なぜここでキャッチしているのかが分からない。 目的や意図の補足がないと、後から読む人にとって意味不明なコメントになってしまいます。
❌ 例3：「TODO」のまま放置されたコメント
// TODO: 最終的にAPIから取得するようにする
✅ TODOは便利だけど、書きっぱなしは“爆弾” になることも。 「誰が？いつまでに？なぜ？」の情報がなく、チーム内での認識ズレを生む原因に。
❌ 例4：過去の仕様に引きずられた“ウソコメント”
// 旧ロジックに対応するためこの処理を残しています
// （でも実際はもう不要になっていた…）
✅ 仕様が変わったのにコメントだけ残っていると、 コメントとコードの内容がズレて混乱の元に。 コードが変わったら、コメントも一緒に見直す習慣が大切です。
🧭 コメントは“書いた瞬間”ではなく、“読み返されたとき”が本番
私も最初の頃は、「とりあえず書いてあるからOK」と思っていました。 でもそれは、「書かれているけど、何も伝わらないコメント」 の完成形だったのです…。
コメントは「未来の誰か」──それはたいてい“未来の自分”ですが──に向けて、 読む価値がある内容になっているか を意識することで、書き方が少しずつ変わっていきました。
💡 第3章：「未来の私が困らないコメント」に切り替えた
何度も同じエラーに引っかかったり、「この処理、なんでこう書いたんだっけ…？」と過去のコードに頭を抱えたり。
そうした経験を経て、私はようやく気づきました。
コメントは、“今の私が分かっていること”よりも、“未来の私がきっと忘れていること”を書くべきなのかもしれない。
✍️ 意識するようになったコメントの観点
✅ 「なぜこの処理があるのか」を書く
// 一部の管理ユーザーだけに表示するため、条件を追加（#124）
→ “どう動くか”より“なぜ必要か”の方が、あとで見たときに役立つ。
✅ 「一見不要そうな処理」にこそ理由を書く
// 初回ロードでダミー値を入れる必要がある（APIの仕様上、空だとエラーになる）
→ 「これ消してもよくない？」と思われそうな箇所にこそ、背景を添える。
✅ 「迷ったポイント」はそのまま書いておく
// ※最初は filter() にしようとしたが、nullを含むため map に変更
→ 技術的な試行錯誤は未来の自分へのヒントにもなる。
🧭 コメントを書くときに心がけること
- 💬 読んだ人が「納得できるか」を基準に書く
- 🕰️ コードよりコメントの方が“賞味期限”が短いと心得る
- 🧹 コードを修正したらコメントも見直す。残りがちな「ウソコメント」を防ぐ
- ✨ 他の人がレビュー時に「なるほど」と思える説明になることを意識する
💡 コメントを書く＝「未来の自分」との対話
コードは「機械への命令」。 でもコメントは、「人への説明」なんですよね。 私はよく、半年後の疲れた自分が見返したときに 「あ〜なるほど、ありがとう私…」って言えるようにコメントを書いています。
✍️ 第4章：私なりに意識しているコメントの書き方
コメントの“あり方”が少しずつ分かってきた頃、
私は自分なりのコメントポリシーを作るようになりました。
あくまで個人ルールではありますが、
「迷ったときはここに立ち返る」ための、シンプルな指針です。
🗣️ 1. コメントは“説明”というより“会話”だと思って書く
- 「自分以外の誰か」が読みながらツッコんでくる前提で補足を書く
- なるべく“ふだんの言葉”で、かしこまりすぎない
// 本当はAPIで取れるはずだけど、タイミング的にまだ値がないことがある
📝 読み手に「なるほど、そういうことね」と思ってもらえれば十分。
🧠 2. “自分の意図や迷い”をメモしておく
- 書いてるときに「どっちにしようか迷った」などの試行錯誤は削除せずコメントに
- 自分でも読み返して「あ〜そのとき悩んでたな」と納得できる
// filter だと undefined を除去してしまうので map にしてます（UI崩れる）
💡 意図があると安心して触れる／後任にもやさしい。
📌 3. 「説明書き」が必要なほど複雑なら、まずコードを見直す
- コメントを一生懸命書こうとして「なぜこれ複雑なんだっけ…」と悩んだら “そのコードが読みづらい”サイン
- 書く前に「そもそも構造を直すべきかも」と立ち止まるようにしています
🎯 4. コメントの“引き際”を意識する
書きすぎても読みづらいだけなので、
- ✅ 意図や背景の補足
- ✅ 詰まりそうなところの注意
- ❌ コードの逐語訳や単なる感想文を区別するようにしています
// リロード時に sessionStorage が消えるブラウザ対策（Safari特有）
→ 背景と理由が明確で、ピンポイント。ちょうどいい塩梅を意識。
✍️ まとめ：コメントに正解はない。でも“心づかい”は残る
何を書けばいいか分からなかった頃、私は「形式」を探していたのかもしれません。 でも今は、「未来の誰かに届くように書く」という“態度”が一番大事なんだなと思っています。
🧼 第5章：コメントも“放置せずメンテナンスする”習慣
コメントは書いたら終わり──
……ではなく、「更新されるコードに合わせて見直す」 のが本当に大切だと、最近実感しています。
❗ なぜコメントの“放置”が危険か？
コードだけ直してコメントが古いままだと：
- 意味がズレて “ウソコメント” になる
- 読んだ人が混乱して「え？処理違くない？」と立ち止まる
- 最悪、バグの原因を見誤ることも…
🔄 私のコメントメンテ習慣
✅ コードを修正するときは、コメントも必ず読み返す
// 処理Aの前提として〜〜（※元々の仕様）
// ↓処理を差し替えたら、ここの前提も見直し忘れず！
✅ “TODO”コメントは期限 or 管理先を明記する
// TODO: ◯月までにAPI対応（issue #512）
💡 「誰が」「何のために」「いつ頃までに」を書くようにしています。
✅ “取り急ぎ”系コメントは期限を決めて見直す
// 応急対応：タイムアウトは10秒固定（後で調整する予定）
→ 忘れるとずっと“仮”のままになりがち。 私は「Notionで“あとで直すリスト”に転記 → 月1で見直し」してます。
🧰 おまけ：見直しのときに便利なコマンド
# コメント内の TODO を検索
grep -r 'TODO' .
# コメント付きの行を確認（JS/TSなど）
grep -Er '//|/\*' .
✨ コメントも“育てる”もの
最初は「一言でもいいから残そう」と思って書いたコメントも、 見直すうちによりクリアに、より伝わる形に進化していきます。
だから私はコメントも、“コードの一部”として ちゃんとメンテされる存在にしてあげたいと思っています。
📝 おわりに
「コメントを書いてね」と言われてはじめたものの、
最初は何を書けばいいか分からず、
とりあえず“説明っぽい言葉”を添えて終わっていた頃の私。
でも失敗やモヤモヤを繰り返していくうちに、
コメントとは単なる“説明”ではなく、
未来の自分やチームの誰かへの「メッセージ」なんだと思えるようになりました。
私はいまでもコメントの書き方に自信があるわけではありません。
ただ、過去の自分と違うのは、
- 「何も書かないと何も残らない」と思えるようになったこと
- 「自分の迷いや意図も、書き残していい」と思えるようになったこと
- 「未来の誰かが困らないように」と自然に思えるようになったこと
です。
コードはロジックを伝えるもの。
コメントは人に伝えるもの。
「自分が読み返したとき、ちゃんと伝わるか？」
──その視点で書くようになってから、コメントは単なるおまけではなく、
チームと自分をつなぐ大事な言葉になっていきました。
この記事が、
「コメントって何書けばいいの？」と迷っている誰かにとって、
少しでもヒントになれば嬉しいです。