9

javadoc コメントで HTML を使用するのは良い習慣ですか、それとも悪い習慣ですか?

Java メソッドのコメントを見ると、先頭にメソッドの名前があり、その後にメソッド ヘッダー全体が続く形式になっているように見えますが、メソッドに javadoc を追加すると、ほとんど判読できません (使用時にポップアップする情報を意味しますコードを書くときのオートコンプリート)。

そこで、Javadoc コメントに HTML を追加してみました。見栄えは良くなりますが、javadoc を生成してブラウザーでコメントを見ると、レイアウトがすべて台無しになっています。

また、HTML を追加すると、コードで直接コメントを読むときにコメントが読みにくくなります。

私のコメントの例:

/**
* <br/>
* <li><b><i>hasChanged</i></b></li>
* <br/><br/><br/>
* 
* <pre>public void hasChanged(boolean changed)</pre>
* <br/>
* 
* This method can notify the observers when a change has occurred in a model.
* <br/><br/>
* 
* The observer can then set the right controls
* <br/><br/>
* 
* @param changed
* <br/><br/>
* Pass true if a model has been changed from it's starting values <br/><br/>
* Pass false if the model has it's initial values<br/><br/>
*/

Java でコメントを記述する方法のベスト プラクティスはありますか?

また、コメントに含めるテキストに関するガイドラインはありますか? たとえば、メソッドのコメントは、常に「このメソッド..」などで開始する必要があります。

4

1 に答える 1

7

あなたの質問に対する「正しい」答えはありません。それは、あなたが javadoc 作業から何を求めているかに大きく依存するためです。ただし、コード自体の表記をできるだけシンプルで整然としたものにすることをお勧めします。

高品質のスタンドアロンの HTML ドキュメントを作成することが目的の場合。特に、ソース コードが存在しないライブラリをドキュメント化している場合は、ソース内の HTML で広範な明示的な書式設定を行うことが、おそらく有用な手法です。

より一般的には、これが私の現在の活動です。要件は、複数の場所で簡単に読み取れるもの、つまりソース コードを作成することです。スタンドアロンのドキュメント; およびEclipseなどのIDEで。Eclipse が HTML 文書から必要なものと同じものを生成する可能性は低いため、その制限を受け入れてフォーマットを最小限に抑えるのが最も簡単です。ツールにその機能を実行させることについては、多くのことが言えます。

独自のデバイスに任せれば、このツールは、新しいユーザーになじみのある形で何かを生成します。それ自体、かなりの「使いやすさ」の価値があります。美しさは見る人の目にある; あなたの好みのフォーマットは、他の人にとっては恐ろしいものかもしれません。

あなたのコメント ('pre' 行) でメソッド プロトタイプを文書化していることに困惑しています。ツールにそれをさせてください。ツールの利点は、マニュアル ドキュメントとコードの間の不一致を防ぐことです。コメントにマニュアル コピーを含めることで、より多くのメンテナンス作業を行うことができます。

フォーマットをシンプルに保つ利点の 1 つは、ソース コードのコメントがその場で簡単に読めるようになることです。これにより、開発者によって正確に維持される可能性が高くなります。

チームで作業していて、他の人が javadoc の品質と一貫した書式設定を維持することを期待している場合は、繰り返しますが、最小限の書式設定を使用することは商業的に意味があります。開発者に意味のあるコメントを書かせることは、適切な場所に "br" を入れてもらうことなしには十分に困難です。

フォーマットをシンプルに保つということは、強調するメリットがなくても明確かつ簡潔な方法で提供しようとしている情報を理解するために、解説の言葉にもう少し手を加えることを意味します。2番目の質問に答えるために、「この方法...」などで埋めません。テキストの量が少ないということは、読者が簡単に閲覧して取り入れられることを意味します.

要約すると、次の理由により、これを行うのは疑わしい方法です (チームで作業している場合は絶対に行わないでください)。

  • ソースコードの可読性
  • 一貫性と正確性の維持
  • 他の人に台無しにされたり、それを修正するために仕事があなたに戻ってくることはありません（何度も何度も）

テキストに正しい情報を入れることに集中してください。ユーザーは、レンダリングされたフォントよりも、その方がありがたいと思うでしょう。

お役に立てれば。

于 2013-08-08T09:05:27.367 に答える