3

私は大学で最終学年 CS の学部生プロジェクト用に Java アプリケーションを書いています。これまで、コードに CheckStyle を使用することは必須であると言われてきました。ただし、デフォルトの CheckStyle 構成を使用するには、すべてのことについて JavaDoc を作成する必要があることがわかりました。名前と実際のコードがそのコードの動作を十分に説明している明らかなインスタンス フィールドとメソッドでさえ、JavaDoc コメントを記述する必要があります。

正直なところ、これは繰り返しであり、コードが雑然としているだけだと思います。これらのコメントがすべてなくても、コードがはるかに読みやすく短くなり、クラスなどを調べる必要があるときに概要を把握しやすくなります。

問題は、checkstyle がそれを問題 (JavaDoc の欠落) として強調表示し、例外なく CheckStyle を使用するように言われた場合、私が望んでいる最後のことであるマークを失うのではないかと思うことです。素晴らしい本から引用します: Martin, Robert C. (2008-08-01). きれいなコード: アジャイル ソフトウェア クラフトマンシップのハンドブック (p. 54)。ピアソン教育 (米国)。

コメントの適切な使用は、コードで自分自身を表現できなかったことを補うことです。失敗という言葉を使ったことに注意してください。本気で言っているんだ。コメントは常に失敗です。それらなしで自分自身を表現する方法を常に理解できるとは限らないため、それらを持たなければなりませんが、それらの使用はお祝いの原因ではありません. したがって、コメントを書かなければならない状況になったときは、状況を逆転させてコードで表現する方法がないかよく考えてください。コードで自分を表現するたびに、自分の背中をたたいてください。コメントを書くたびに顔をしかめ、自分の表現力の欠如を感じるべきです。なぜ私はコメントにそんなに落ち込んでいるのですか？彼らは嘘をついているからです。常にではなく、意図的にではありませんが、あまりにも頻繁です。コメントが古いほど、記述されているコードから離れているほど、単純に間違っている可能性が高くなります。理由は簡単です。プログラマーはそれらを現実的に維持することはできません。

上記にどれほど心から同意するかは言えません。コメントは私の目にはただの混乱です。関連する場合は、コメントがあります。

したがって、私の質問は次のようになります。上記の本を読んで得た自分の信念と知識/アドバイスに固執する必要がありますか、それとも CheckStyle 標準に準拠し、JavaDoc コメントの欠如によるマークダウンのリスクを排除する必要がありますか? ?

4

1 に答える 1

3

あなたは言う：

ただし、デフォルトの CheckStyle 構成を使用するには、すべてのことについて JavaDoc を作成する必要があることがわかりました。名前と実際のコードがそのコードの動作を十分に説明している明らかなインスタンス フィールドとメソッドでさえ、JavaDoc コメントを記述する必要があります。

また:

Sun が提案するもの、つまりデフォルトの checkstyle 構成に固執するのが最善だというスーパーバイザーに尋ねました。

これら 2 つのステートメントは一貫していません。

これは、実際の、伝統的で、古い Sun のコーディング規則文書です (1999 年に改訂されたもの):

コメントのセクションには次のように書かれています。

自明でない、または明白でない設計上の決定についての議論は適切ですが、コードに存在する (およびコードから明らかな) 情報を複製することは避けてください。冗長なコメントは簡単に時代遅れになります。一般に、コードが進化するにつれて時代遅れになる可能性があるコメントは避けてください。

すべてのメンバーがコメントを必要としているわけではありません。

「明白なインスタンスフィールド」または「名前と実際のコードがそのコードの機能を十分に説明しているメソッド」のいずれにもコメントが必要ないことは明らかだと思います。Sun のコーディング規則とデフォルトの Checkstyle 構成との間の等価性を引き出す際に、監督者の指示またはそれに対するあなたの解釈のいずれかが誤りです。

また、Sun のコーディング規則は、 Java 自体を作成しているプログラマーによって、プログラマーのために作成されたものであることも覚えておく価値があります。それは非常に特別な種類の仕事です。彼らは機能するコードを生成し、メンテナーが理解できるコードを作成するだけでなく、バ​​イナリ形式でのみ配布される標準ライブラリを作成していたため、理解可能であり、多くの場合、署名と署名によって完全に指定されていました。コメントだけ。1990 年代に開発された Java 自体の実装用のルールを、現在記述されているアプリケーション コードに適用するのは非常にばかげていると思います。それは、レビ記に従って自分の人生を生きるようなものです。

于 2012-11-17T23:42:02.023 に答える