5

私はこのフォーラムを調べましたが、これをグーグルで検索しましたが、同じクラスに一緒に表示されるJavadocとアノテーションを処理するための最良の方法がわかりません。

Sun / Oracleのドキュメントからわかるように、Javadocを注釈の上にリストする必要があることを示唆しているようです（明示的なステートメントは実際には見つかりませんが）。

APIを非推奨にする方法と時期の例を参照してください。

これは、@Deprecatedや@Overrideのような単純なものに最適です。しかし、JPAやHibernateを使用する場合はどうでしょうか。クラスとメソッドには、かなり多くのアノテーションが付けられる必要があります（クラスまたはメソッドごとに2つ以上のアノテーションが付けられる場合もあります）。

Javadocはまだアノテーションの上にあると思いますか？

また、注釈をどのように使用するのが最適か疑問に思います。クラス、メンバー、メソッドの上にアノテーションが「スタック」する例を見てきました。そして、同じ行に注釈をリストしている他の人を見たことがあります（通常はここのメソッド）。

どちらがベストですか？どちらが読みやすいですか？

そして、Javadoc内で何かに注釈を付けたかどうかという事実を「文書化」しますか？

私はこれについての優れたドキュメントのセット、および/または最も読みやすく/保守しやすいものについてのあなた自身の経験のいずれかを探しています。

4

2 に答える 2

7

Javadocは、クラスやメソッドなどを文書化する場所にすぎません。アノテーションは、特定のコードの機能を変更できます（HibernateやSpringのアノテーションなど）。したがって、私にとっては、アノテーションをコードに近づける必要があることは明らかです（つまり、javadocとメソッド/関数の間）。

しかし、注釈がたくさんあるところで、どのように注釈を書くのでしょうか？場合によっては、短い行で何らかの方法で接続されている場合を除いて、それらを別々の行に残すことを好みます。

アノテーションを使用していることをJavadocで明示的に文書化することは、私が思うに良い考えではありません。アノテーション@Documentedには、生成されたjavadocsに表示される必要があることを示すアノテーション自体を含めることができます。これに加えて、それは実装の詳細です-javadocは、それをどのように行っているかではなく、どのメソッド/オブジェクトが作成されているかを通知する必要があります（ほとんどの場合、少なくとも）。

于 2011-08-08T14:18:23.597 に答える
0

コード注釈と javadoc 注釈を混同していると思います。

javadoc コメントはまさにそれです: コメント。アプリケーションにとって、実際に何が囲まれているかは問題ではありません/** */(もちろん、javadoc を生成しない限り)

コード注釈は実際にアプリケーションの機能に影響を与えます。注釈を省略した場合 (および休止状態の構成ファイルを提供しない場合)、休止状態のマッピング クラスは機能しません。@Deprecatedjavadoc コメントのみでマークされ、コードではマークされていないメソッドは、コンパイラによって非推奨として認識されません。(その場合、javadoc ツールが警告を表示する可能性があります)

はい、同じ名前を共有するコードとjavadocに注釈がありますが、それらはまったく異なります。@Deprecatedコード内で非推奨としてマークし、その理由を文書化するために、両方を使用する必要があります。

于 2011-08-08T14:16:46.530 に答える