巷では「コメントを書いた方が良い」「いや書かなくて良い」という話を見かけますが、コメントは書きましょうという話をします。
まずはコメントを書く練習をしよう
良いコメントを書くためには当然コメントを沢山書く経験が必要です。通常のコードやテストコード、ドキュメントなどと同じです。
ところがあまりコメントを書いたことが無い人が「～ならコメントは要らない」という話をしているように見えます。
テストコードをほとんど書いたことが無い人が「～ならテストコードは要らない」と言っているのと同じで全く信用できません。
コメントは書きましょう。
次に、よく以下のようなコメントは意味が無いから書かなくて良いという話があります。
list.add(user); // ユーザをリストに加える
実際、このようなコメントは無意味な場合が多いです。
しかしコード同様、初めてコメントを書く人のコメントの質が低いのは当然のことです。
気にせずどんどん書きましょう。次第に良いコメントが書けるようになります。
言い訳の一つにコメントとコードが一致しないことがあるからコメントは無い方がマシという話を見かけます。
レビューの無いチームで開発しているならそうかもしれませんが、普通はレビューで指摘されるでしょう。
見逃してしまった場合も、バグやtypo同様に気づいたときに直せばよいだけの話です。
また、コメントに限らず仕様書や設計、構成図もコードと乖離することがあります。
しかし乖離する可能性があるから仕様も構成図もありませんとするのは個人開発でない限りあり得ない態度ではないでしょうか。
ドキュメントコメントは必ず書こう
このリストに要素がない場合にtrueを返します。
ArrayList#isEmpty
明らかに関数名で分かるし誤解のしようがない関数であっても、ドキュメントコメントは書くのが当然です。書きましょう。
公開ライブラリではないから不要と思うかもしれません。しかし各プログラマが要・不要を考えるくらいだったら全部書きましょう。「関数名から分かる」などと考え始めると次第にサボるようになります。
ドキュメントコメントを書こうとするとうまく説明することができず、結果として関数自体が複雑な事に気づくこともあります。
コメントはやや過剰に書こう
コメントを書いていると「まあコード見ればわかるな」と感じることはよくあると思います。
しかし、今一番仕様に詳しい実装者のあなたが見ればわかるからと言って、初見のレビューアや次にコードを修正する人がすぐにわかるとは限りません。
「AをするためにはBというコードを書く必要がある」というところまで理解しているとまるでAというコメントは冗長に思えてきますが、
実際はその理解するまでの時間がかかります。他の人のその時間を減らしましょう。