ソースコードのコメントについて

イワタシステムエンジニア（SE）

私はコメントをしっかり記載していました。
以下私の個人的な経験からお話させて頂きます。
プログラムに関するプログラム詳細仕様書やメソッド詳細仕様書というようなものを別途作成されているのであれば、プログラム自体に記載するコメントは最低限のものでいいと思います。（あくまでも仕様書にある記載内容と実際のプログラムの内容に相違がないことが前提です。）
しかしながら最近では、プログラム自体を対象とした仕様書を作成するケースはあまり見受けられませんし、メソッドに関する仕様書のようなものも、その機能については記載がされていてもロジックレベルにまで言及されていないのが一般的でしょう。そういう場合は、やはり可能な限りプログラムソースにコメントを残すべきです。
優秀なプログラマであればあるほど、よく見受けられるのですが、いったい誰のためにそのプログラムを作っているのかを理解できていない人がおられます。
自分のためにプログラムを作るのでしょうか。自分のためにシステムを構築するのでしょうか。違いますよね。クライアントのためですよね。その製品を使う人のためですよね。
そこを勘違いして自己満足とでも取られるような理解しづらいプログラムを作る人が非常に多いです。しかもそういう人に限って、プログラムの見栄えが悪くなると思うのか、ろくにコメントを残さない。
確かに実際に動かしてみると要求どおりに動いているし処理レスポンスも悪くない。ですがそのプログラムを作ったプログラマが、この先一生そのプログラムのメンテをするわけではありません。場合によってはソースを含めて一切をクライアントに引き渡して、その後のメンテをクライアント側で行うことが多々ありますし、そうでなくても違うプログラマがそのプログラムの保守を行う場合が珍しくありません。そしてクライアント側の担当者や他のプログラマが必ずしも作ったプログラマと同等レベルであるとは限りません。
さほど優秀ではなくとも一般レベルのプログラマが、仕様書の類がなくて、かつコメントが記載されていないプログラムを見た時、果たしてどう思うでしょうか。仕様変更や機能追加が発生して、そのプログラムを修正しなくてはならない場合、何と思うでしょうか。
どこをどう直せばいいか考え悩み、その調査に思いもしなかった時間を取られることになるでしょう。また仮に修正する箇所がわかったとしても、そこを修正することで他の機能に影響が出ないか。例えば「ここを修正した場合、XXXXXプログラムの○○○○○部分をも修正する必要あり」というようなコメントがあるのとないのとでは、その後の作業に及ぼす影響度合いに雲泥の差が出るのです。
どんなに優れたプログラムであっても、仕様書がなかったり、ロジックに関する最低限のコメントが記載されていなかったりする等、保守性の低いプログラムは、いつの時代も敬遠されますし後々に問題を引き起こす可能性が大です。何でもかんでもコメントを記載するべきだとは思いませんが、できるだけ誰でもが理解できるよう必要最低限のコメントは記載しておくべきだと思います。

ゆうとプログラマー

ソースコードのコメントについては、私は心配なので書きたいと感じます。もしも他の人がみて悩んでしまったときや、自分が見返すときに解りやすく見返せるためにもソースコードのコメントは書きたいところです。
一方、私の同僚の中にはソースコードのコメントを書くとリズムが崩れるから嫌だというような人もいましたし、コメントがあることで読みにくいと言う人もいます。

確かにメソッドや変数名を英語で書くときもそれがどんなものなのか解るようなメソッドや変数名をしっかりと英語で書くことを心がければコメントは必要ないという意見もわかります。そして何よりも職場の支持でコメントは書かなくてもいいと言われているのであればそれに従っていれば問題はないでしょう。

私が書いてきたコードはもしコメントがなかったとしても他人はある程度理解できるという自信はありますが、書いたほうが自分の気持ちとしては確実にメッセージが伝わるので安心できますよね。