- コメントというのは、プログラムのコードの中に書き込む、人間が読むための説明メモのことだよ。
- コンピュータはこの部分を無視して実行しないから、コードの意図や注意点を未来の自分や仲間に伝えるために使える。
- 上手にコメントを残せるようになると、数ヶ月後の自分やチームメンバーがコードを読み解く時間を大きく減らせます。
【深掘り】これだけ知ってればOK！
プログラムは、コンピュータへの命令の集まりです。しかしそのコードは、後から読む人間にとって意図が分かりにくいことがよくあります。なぜここでこの処理をしているのか、この数字は何を意味するのか——書いた本人ですら、数ヶ月後には忘れています。そこで、コードの傍らに人間向けの説明を書き添えるのがコメントです。コンピュータは実行時にコメントを完全に無視するので、どんな言葉で書いても動作には影響しません。プログラムに貼る付箋、あるいは設計図の余白に書き込む注釈のような存在だと考えるとしっくりきます。
コメントの書き方は言語によって違いますが、多くは特定の記号で示します。一行だけ説明する形式と、複数行をまとめて囲む形式の二種類が一般的です。もう一つ覚えておきたいのがコメントアウトというテクニックで、これは動いているコードを一時的にコメント扱いにして、実行されないようにする使い方です。バグの原因を探るとき、一部の処理を止めて挙動を確かめる場面で重宝します。
たとえば変数xに1を足すとコメントするのは、コードを見れば一目瞭然なので価値が薄いものです。一方、税率改定により係数を変更といった背景や理由の説明は、コードだけでは決して読み取れない貴重な情報になります。また、コメントとコードの内容がズレると、かえって読み手を混乱させます。コードを修正したらコメントも必ず更新するという規律が欠かせません。書きすぎず、しかし要所は押さえる。このさじ加減が、読みやすいコードを支えています。
よくある誤解
コメントは多いほど親切という誤解
たくさん書けば良いというものではありません。コードを読めば分かる内容をいちいち説明したコメントは、画面を埋め尽くして肝心のコードを読みにくくします。さらに、コード変更時に更新が漏れると、誤った情報を伝える有害な存在に変わってしまいます。
コメントを書けばコードが整理されるという思い込み
分かりにくいコードに説明を付け足せば済む、という考えは順序が逆ではないでしょうか。本来は、変数名や関数名を工夫し、処理を整理して、コメントがなくても読めるコードを目指すのが先です。コメントはそれでも伝えきれない意図を補う、最後の一手と捉えるのが健全です。
会話での使われ方
この関数、何のための処理かコメントが一行もないんですよね。半年後に読む人のために、意図だけ書き添えてもらえますか。
先輩エンジニアがプルリクエストのレビューで、後輩に依頼している場面です。
とりあえずこの処理コメントアウトして動かしてみて。それでエラー消えたら原因はそこです。
ベテランエンジニアが、デバッグで詰まった同僚にSlackで助言しているカジュアルなやり取りです。
コメント規約が人によってバラバラで、可読性に差が出ています。チームでコメントの書き方ルールを揃えませんか。
テックリードがチームの振り返りミーティングで、改善を提案している場面です。
【まとめ】3つのポイント
- 人間のための説明メモ：コメントとは、コード内に書く人間向けの説明で、コンピュータは無視するため動作に影響しません。
- なぜを残すのが価値：何をしているかではなく、なぜそうしたかという背景や理由を書くことで、後から読む人を助けます。
- 書きすぎず更新を忘れず：過剰なコメントは可読性を下げ、更新漏れは誤情報になるため、要所を押さえつつコード変更時に合わせて直すことが大切です。
よくある質問
-
Qコメントはどんなときに書くべきですか？
-
A
結論として、コードだけでは伝わらない理由や背景がある場面で書きます。複雑なロジックの意図、特殊な値を使う事情、暫定対応の注意書きなどが典型です。逆に、コードを読めば自明なことは書かない方がすっきりします。
-
Qコメントアウトとは何ですか？
-
A
動いているコードを一時的にコメント扱いにして、実行されない状態にすることを指します。バグ調査で特定の処理だけ止めて挙動を確認したいときや、後で使うかもしれないコードを残しておきたいときに使います。
-
Qコメントを書くとプログラムは遅くなりますか？
-
A
なりません。コメントはコンピュータが実行時に完全に無視するため、処理速度には一切影響しません。安心して必要な説明を書いて大丈夫です。読みやすさが向上する分、むしろ開発全体の効率はよくなります。
-
Qコメントとドキュメントとの違いは何ですか？
-
A
対象と場所が異なります。コメントはソースコードの中に直接書く、その箇所限定の説明です。一方ドキュメントは、コードとは別に作成する、システム全体の仕様や使い方をまとめた資料を指します。読み手も、コメントは開発者向け、ドキュメントは利用者や運用者も含む広い範囲を想定する点で違います。
この用語と一緒に知っておきたい用語
| 用語 | この記事との関連 |
|---|---|
| プログラム | プログラムを押さえると本記事の理解がさらに深まります。コンピュータに何をどの順番でさせるかを書き並べた指示書、それがプログラムだ |
| アイコン | アイコンを押さえると本記事の理解がさらに深まります。アプリやファイル、操作ボタンなどをひと目でわかる小さな絵で表したもの、それがアイコンだ |
| 可読性 | 次のステップとして可読性を学ぶと知識が広がります。可読性の主要な特徴と用途を理解することで、関連する技術・制度・概念を正確に把握できるようになる |
| ソース | ソースを押さえると本記事の理解がさらに深まります。プログラマーが書いた、アプリやWebサイトの「設計図（レシピ）」のことだよ！ |
| プルリクエスト | 次のステップとしてプルリクエストを学ぶと知識が広がります。自分が作成したプログラムの変更内容を、チームの仲間にチェックして取り込んでもらうための依頼通知のこと！ |
【出典】参考URL
MDN Web Docs JavaScriptの構文とコメント: コメント記法の解説 https://developer.mozilla.org/ja/
Python公式 PEP8 コーディング規約: コメントの書き方指針 https://peps.python.org/pep-0008/
IPA 情報処理技術者試験シラバス: ソースコード可読性の基礎 https://www.ipa.go.jp/
コメント