日々常々

ふつうのプログラマがあたりまえにしたいこと。

ソース内のコメント

Javaでも多くのプログラミング言語と同様にソース内にコメントを書くことが出来ます。
<蛇足:コメントの種類とか>コメントには、単一行コメントと複数行コメントがありますが、基本的に使うのは単一行コメントです。複数行コメントは滅多に使わない、と言うか使いません。せいぜい複数行のソースコードを一時的にコメントアウトする場合かつ手を抜きたい場合くらいなものです。複数行コメントは開始終了が読み取り辛く、コメントされているところをさらにコメントで囲もうとするとコンパイルが通らなくなるし、長期的に置かれるコメントには向きません。理由は色々ありますが、基本的に単一行コメント以外は使っていません。</蛇足>
ソース内に書くコメントの密度、水準には色々と主張があり、同じプロジェクトの中である程度コーディング規約が定められていても、最終的にはプログラマ個人の裁量に任されてしまっていたりします。そして、お堅い方々にはコメントあるべし、と言った主張も根強いようで、コメント不要と判断してコメントなしで書いたソースを何故か読めもしないのにレビューして、1行ごとに無駄なコメントを付ける様に主張してきたりします。
確かにコメントが無ければ読みづらいソースもあります。ですが、無駄なコメントは極力あるべきではありません。1行ごとにこの行が何であるかを日本語で説明しなければならないような事がありえるはずがありません。OOPができていなくても、それなりに構造化プログラミングが出来ていれば、クラスやメソッドJavaDocコメントで大抵は事足ります。*1
私の経験上では、コメント量はプログラマの裁量に任されています。コメントによって挙動が変わったりはしない事もありますが、未だにプログラミングという仕事の量がステップ数、つまり記述した行数で計られている事もあります。お金を払う側からすれば、ステップ数にカウントされないコメントは有っても無くても同じものとして扱わなければ、コメントに対して何かしらのコストをかけなければいけないため、今まで無視してこれていたコストをかけたくないのかもしれません。長年運用されており、今後も保守されていくであろうシステムにも拘らず、コード内の保守性は置き去りになっています。駄目な事は判っているのに、「今動けば良い」と言う発想で開発が続けられていく限りこの辺りは変わらないのでしょう。
一貫したコメントの付け方が明文化することはほぼ不可能だと思います。可能なのは、全く付けないという暴挙に出た時のみでしょう。コメントの必要性はプログラマ、もしくはそれに準じるコードを直接読む人の力量に左右されており、読み手にとって必要以上のコメントは全てノイズであり、読み手にとって不十分なコメントはコードを読む助けにはなりません。一定以上の力量を持った人のみが読むのであれば、それを念頭においてコメントを記述することは出来ますが、どこの馬の骨とも知れない、殆ど素人がプログラマとして入ってくるような業界ですので、それもある程度は想定してコメントを書かざるを得ません。これ位なら判ってほしい、と念じてコメントを記述している今日この頃です。

*1:その際のメソッド名やクラス名が変な場合は別ですが。