Javaのコメントの書き方の話
ソースレビューしてたら先輩社員とコメントの書き方について揉めた意見の交換ができたので、その話。
背景
外注の方が、プロジェクトにアサインされて実装をお願いすることになったのですが、当然最初なので少し実装をしてもらったところでソースレビューを行いました。 その時に、たまたま聞こえる範囲にいた先輩が覗きに来て、そのまま2人でレビューをしました。 その中で、（色々とあるにはありますが中でも）特にコメントの書き方で意見が別れたので書いてみます。
コメントを書く粒度
先輩
すべての処理(行)にコメントを記述すべきだ。自分
変数名やメソッド名などで処理の内容がわかるなら不要。
設計書の内容
先輩
書くべき。設計書の変更を行う際にソースコードのどの位置を変更すればいいのかわからんくなるから。自分
書かないべき。設計書の変更があった際にソース上のコメントを変更し忘れた際に、どっちを信じたらいいのかわからなくなる。コメントのメンテナンスコストもバカにならない。
変更履歴
コメントのないコードは
先輩
(例外なく)糞。自分
(読めるなら)美しい。
お互いの主張
先輩
ソースを触る人間はPGだけじゃなくて、ソースが読めないSEやPMの場合だってある。その場合にコメント無しでどうやって修正などするんだ。自分
コメントは実際に動作する処理とは無関係で、触らなきゃいけないのはソースそのもの。コメントが多いとその分ノイズとなって修正すべき箇所が見つけにくくなる。
考察？
お互い立場も違うので意見の相違はあるとは思うし、確かにソースが全く読めない人間からしたらコメントはあったほうがいいのかなぁ。
（なんでソース全く読めない人間が触る想定なんだよ)
