「良いコメント」って結局何？　「悪いコメント」に隠れた“深刻な問題”とは？

プログラマーが書くコメントの良しあしは、自分だけではなく、他のプログラマーの生産性にも影響を及ぼす。「良いコメント」とはどのようなものなのか。「悪いコメント」はなぜ駄目なのか。

公開 2023年06月25日 09時30分

更新 2023年06月30日 11時12分

著者

Matthew Grasberger

[TechTarget]

印刷する連載新着通知を受け取る

　「良いソースコード」を書きたいと考えているプログラマーにとって、決して軽視できないのが「コメント」だ。どれほど優れたプログラムを実現するソースコードでも、適切なコメントがないと、デバッグや機能追加といったメンテナンスがしにくい“駄目なソースコード”になってしまう可能性がある。

「良いコメント」の条件と「悪いコメント」に隠れた深刻な問題

併せて読みたいお薦め記事

連載：プログラマーが知るべき「良いコメント」の条件

ソースコードの書き方

　良いコメントとは「読んだ人が、ソースコードが定義する処理を大まかに理解でき、全体の流れが分かる」コメントだと言える。そのようなコメントを含むソースコードは、コードベース（ソースコード群）や使用中のフレームワーク（特定の設計思想を具現化するプログラム部品やドキュメントの集合体）を詳細まで理解する助けになる。

　複雑で特殊なソースコードを要約するコメントは、ソースコードのレビューやメンテナンスの時間短縮の一助となる。適切なコメントやソースコードは、プログラマーがレビューやメンテナンスに必要な情報を簡単に理解できるようにする。

　良いコメントの別の要件として「簡潔である」ことが挙げられる。簡潔なコメントを書くのに苦労するのであれば、ソースコード全体に問題がある可能性がある。そうした場合は、ソースコードの構成を見直すとよい。

　複雑過ぎるソースコードは読みづらく、コメントを挿入するのに苦労する。説明しやすいソースコードにリファクタリング（動作を変えないままの内部構造修正）をすることで、他の人がソースコードを素早く理解できるようになり、ソースコードのメンテナンスもしやすくなる。

　次回は、実例を交えて「良いコメント」とは何かを考える。