[そのコメントは必要、不要!?]プログラミングでのコメントの使い方

対象読者

コメントとは、プログラムの動作に影響を与えない文章のことだ。プログラムに注意や補足情報をコメントとして併記することで、プログラムを理解しやすいものにできる。

それは本当だろうか？

適切にコメントを使わなければ、むしろプログラムを読みにくいものにしてしまう危険性がある。

効果的なコメントとは、コードだけでは読み取れない情報を付加するために使われる。

以下では、例を通して、コメントの望ましい書き方や、考え方について確認する。

以下のようなコメントに意味はあるだろうか？

# 整数を足し合わせたものを変数に格納する
plused = 1 + 2

処理に意味は元々のコードは読めば分かる。にも関わらず、コメントを書く意味はあるのだろうか？

そもそも、なぜコメントを書くのだろうか。

それは、ソースコードを読んでも得られない情報をメモすることで、コードの理解を援助するためだ。例えば、

などだ。

それ以外のコメント、特に、読めば直ぐに分かるようなものはむしろ有害である。

なぜならば、コードはリーダブルを目指して書くべきだからだ。

書籍リーダブルコードでは、以下のコードを目指すべきだとしている。

初学者に多い。些細なことに関しても、逐一コメントを書かくべきである、という考えに対して、このように命名してみた。

プログラミングの授業でもコメント書けとしか指導されなかった。ブログ等の入門記事では、分かりやすいように、逐一コメントが書かれている例があることもなんでもコメント症候群に拍車をかける原因となっている(と思う)。

プログラミングにおいて、名前は重要だ。適切な名前は、プログラムの挙動に関する情報をあたえてくれる。

名前が適切ならば、コメントが不要になる場合がある。

例示

以下のように、処理のまとまりに対してコメントが書いてあるコードを見たことはないだろうか？

改行を挟むことによって、この羅列は一つの目的のための処理だとグループを明示するためにコメントを使うこともある。

しかし、より改善できる場合がある。その処理を関数として抽出することだ。

関数の抽出によって、

名前はコメントになる。処理の意図を伝える手段になるからだ。

コメントは、コードの改修が進むにつれて、コードの注釈としての機能が失われることがある。コードの改修に伴って、コメントも修正しなければならないのに、それを怠った場合、そういった事態が生じる。コメントはプログラムの動作に影響を与えないが故に、コメントの保守をしなくても、問題が発生しないからだ。

コードの振舞いの変更に伴って、コメントの変更も強制されることが理想である。

さらに、名前を用いることによって

私の職場には、コードに引き継ぎのために、丁寧にコメントを書くべきだ、と主張する先輩がいる。