私は大学で最終学年 CS の学部生プロジェクト用に Java アプリケーションを書いています。これまで、コードに CheckStyle を使用することは必須であると言われてきました。ただし、デフォルトの CheckStyle 構成を使用するには、すべてのことについて JavaDoc を作成する必要があることがわかりました。名前と実際のコードがそのコードの動作を十分に説明している明らかなインスタンス フィールドとメソッドでさえ、JavaDoc コメントを記述する必要があります。
正直なところ、これは繰り返しであり、コードが雑然としているだけだと思います。これらのコメントがすべてなくても、コードがはるかに読みやすく短くなり、クラスなどを調べる必要があるときに概要を把握しやすくなります。
問題は、checkstyle がそれを問題 (JavaDoc の欠落) として強調表示し、例外なく CheckStyle を使用するように言われた場合、私が望んでいる最後のことであるマークを失うのではないかと思うことです。素晴らしい本から引用します: Martin, Robert C. (2008-08-01). きれいなコード: アジャイル ソフトウェア クラフトマンシップのハンドブック (p. 54)。ピアソン教育 (米国)。
コメントの適切な使用は、コードで自分自身を表現できなかったことを補うことです。失敗という言葉を使ったことに注意してください。本気で言っているんだ。コメントは常に失敗です。それらなしで自分自身を表現する方法を常に理解できるとは限らないため、それらを持たなければなりませんが、それらの使用はお祝いの原因ではありません. したがって、コメントを書かなければならない状況になったときは、状況を逆転させてコードで表現する方法がないかよく考えてください。コードで自分を表現するたびに、自分の背中をたたいてください。コメントを書くたびに顔をしかめ、自分の表現力の欠如を感じるべきです。なぜ私はコメントにそんなに落ち込んでいるのですか?彼らは嘘をついているからです。常にではなく、意図的にではありませんが、あまりにも頻繁です。コメントが古いほど、記述されているコードから離れているほど、単純に間違っている可能性が高くなります。理由は簡単です。プログラマーはそれらを現実的に維持することはできません。
上記にどれほど心から同意するかは言えません。コメントは私の目にはただの混乱です。関連する場合は、コメントがあります。
したがって、私の質問は次のようになります。上記の本を読んで得た自分の信念と知識/アドバイスに固執する必要がありますか、それとも CheckStyle 標準に準拠し、JavaDoc コメントの欠如によるマークダウンのリスクを排除する必要がありますか? ?