ソースコードのコメントはしっかり書くべき

プログラミングにおいて、"ソースコードに記述するコメント"に対するスタンスとして、

「コメントは極力書かないようにする。なぜなら、ソースコードを見てそのまま意味が分かるのが良いプログラムであるからだ。」

という意見があります。僕もまだプログラミングを覚えたての頃はそうかもしれないと思い、自分がコメントの少ないソースコードを読むのに苦労しているのは、単純に経験不足のせいだと思っていました。

しかし、何年も実際に仕事でプログラミングの経験を積んだ現在、はっきりと断言できます。コメントを書くべき場合というのは存在します。「ソースコードを見てそのまま意味が分かるのが良いプログラムである」という言葉を単純に信じてはいけません。そして、コメントを書かなくて困る場合はあっても、書きすぎて困ることはありません。だから僕はソースコードのコメントはしっかり書くべきだと思っています。

たとえソースコードの意味が完全に理解できたとしても、外部から渡される引数の意味や取りうる値など、ソースコードには書かれないものの動作を理解するために不可欠な情報がありますからね。

また、ソースコードをどのような意図で書いたのか、など、ソースコードを読む開発者にとって知りたい情報もあります。

もちろん書きすぎはよくありませんが、オブジェクト指向プログラミングならば、全てのメソッドについて目的と各引数・返り値の説明くらいは例外なく全部コメントを書くべき、というのが僕の意見です。

そんなのソースコード見りゃ分かるって？嘘ですね。確実に嘘です。

だったら、他人の書いたソースコードを読んでいる時を思い出してみればいいですよ。全くコメントがない状態だと、たった1行からなるメソッドですら、そのメソッドの意図や引数の取りうる値やどんな返り値になるのかを推測するのが大変な場合なんて腐るほどあるでしょ。この業界でエンジニアやってれば経験があるはずですよ。

結局コメントを書くのに反対する意見って単純にコメント書くのが面倒なだけって気がするんですよね。いいから書こうよ、って思います。

※この記事について指摘・意見・提案・感想などありましたら下のコメント欄にどうぞ。