コメントは適切に使うべし

注意: この記事は1年以上前に掲載されたものです。情報が古い場合がありますのでお気を付け下さい。

チームで開発を行っている時にコメントの使い方は結構ばらつきがあり、どうしてもそれぞれのやり方が出てしまうが、個人的には余計なコメントは不要と考えている。もちろん、適切なコメントがあることによって何をしているのかが理解しやすくなるというメリットはあるものの、そうではないコメントは害悪になってしまう。

個人的には以下のコメントは重要なものと考えている。

  • 見ただけでは理解不能な処理を説明するコメント
  • ドキュメント・仕様書となるコメント

まず、「見ただけでは理解不能な処理を説明するコメント」についてだが、どうしても処理の関係上、見ただけでは何を行っているのかわからないものが出てくるときがある。その時にそれは何を行っているのかをコメントにすることによって、確認する手間が省ける。特にアセンブリ言語では効果を発揮する。もっとも、コメントと実際の処理が間違えていたら問題だが。

次に、「ドキュメント・仕様書などのベースとなるコメント」だが、これはJavadocやHeaderDoc、Doxygenなど、特定のコメントをパースしてAPI仕様書を作ってしまうというものである。実際の開発ではあまり意識することはないが、仕様書を作る時にこれがあるかどうかで手間が大幅に変わってくる1 。また、これらのコメントは最近のIDEでは解析して関数や変数の意味を説明してくれるケースも増えているため、わざわざ実際のコードを確認するだけの手間も減らせる利点も大きい。

以下のコメントは不要と考えている。

  • 意味不明なコメント
  • 更新内容を書いたコメント

まず「意味不明なコメント」は読むだけ無駄であるため、不要である。

「更新内容を書いたコメント」については、今日のバージョン管理システムの強化によって、以前と比較して不要になっている。それよりも、コミット時の説明をしっかりと行うのが望ましいだろう。とはいえ、これについては、重要な変更などでこれがないと致命的な問題を引き起こしかねないものについては、コメントに残した方が良いかもしれない。

ざっと、個人的に重要なコメントと不要なコメントをあげてみた。コメントはうまく使いこなしたいものである。

ウェブマスター。本ブログでITを中心にいろいろな情報や意見などを提供しています。ご用の方はコメントかコンタクトフォームにて。

  1. コメントが書いていれば設定ファイルを定義した上でコマンド一発で出来てしまうほど簡略化ができる []
スポンサーリンク

フォローする