Alibaba Java開発マニュアルのアノテーション規則とJavadocタグおよびJavadocアノテーション仕様
私は最近ソースコードを見て、Javadocでいくつかの一般的なコメントを整理しました
Javadocは、Sunが提供する技術であり、クラス、メソッド、メンバーなどの注釈をプログラムのソースコードから抽出して、ソースコードと一致するAPIヘルプドキュメントを形成します。
Javadocコマンドは、以下を使用して独自のAPIドキュメントを生成するために使用されます。
javadocソースファイル名.java
javadoc -dファイルストレージディレクトリソースファイル名
.javaはIDEAを介してJavadocを生成します：ツール-> JavaDocを生成
javadocタグ
| ラベル | 説明 |
|---|---|
| @著者 | 著者ID |
| @バージョン | バージョンナンバー |
| @return | 関数の戻り値の説明 |
| @deprecated | 期限切れのAPIを識別します（互換性を確保するため、引き続き使用できますが、推奨されません） |
| @throws | コンストラクターまたはメソッドによってスローされた例外 |
| @例外 | 同@throws |
| @見る | 参照、クラス、メソッド、変数などの関連コンテンツの表示は、ヘッドに記述する必要があります |
| {@link包。类#member} | 参照、@ seeと同じですが、任意の位置に書き込むことができます |
| {@値} | 定数コメントについては、その値がドキュメントに含まれている場合、ラベルを変更して定数の値を参照してください |
| {@コード}} | {@code text}テキストをコードとしてマークすると、}に解析されtextます。Javadocでは、クラス名またはメソッド名が関係している限り、@ codeでマークする必要があります |
| @param | 説明メソッドのパラメーター |
| @inheritDoc | 親クラスのJavadocを継承するために使用され、親クラスのドキュメントコメントは子クラスに継承されます |
javadocコメント仕様
1つは、Javaのドキュメント
// 注释一行
/ * */ 注释若干行
/** ……*/ 注释若干行，写入Javadoc文档
2.文書の形式
カテゴリに書かれた文書の注釈は、一般に3つの段落に分かれています。
- 最初の段落：概要の説明。通常は、このタイプの役割を簡単に説明するための文または段落で、英語のピリオドで終わります
- 2番目の段落：詳細な説明。通常、このタイプの機能を詳細に説明するために1つ以上の段落が使用されます。通常、各段落は英語のピリオドで終わります
- 3番目の段落：作成者、作成時間、参照カテゴリ、およびその他の情報をマークするために使用されるドキュメントアノテーション
生成文档是HTML格式。
换行<br>
分段<p>(写在段前）)
例
/**
* show 方法的简述.
* <p>show 方法的详细说明第一行<br>
* show 方法的详细说明第二行
* @param b true 表示显示，false 表示隐藏
* @return 没有返回值
*/
public void show(boolean b) {
frame.show(b);
}
Alibaba Java開発マニュアルに関する注記
- クラス、クラス属性、クラスメソッドアノテーションは、JavaXX仕様を使用する必要があります。//XX コンテンツではなく、/ * content / formatを使用する必要があります。
- すべての抽象メソッド（インターフェース内のメソッドを含む）には、Javadocで注釈を付ける必要があります。戻り値、パラメーター、および例外の説明に加えて、それらはメソッドの機能と実装する機能も示す必要があります。
- すべてのクラスで作成者と作成日を追加する必要があります。
- メソッド内の単一行コメントの場合、コメント化されたステートメントの上で新しい行を開始し、//コメントを使用します。メソッド内の複数行コメントの場合は、/ * * /コメントを使用し、コードとの位置合わせに注意してください。
- すべての列挙型フィールドには、各データ項目の目的を説明するコメントが必要です。
- 熟練していない英語を使用して注釈を付ける代わりに、中国語の注釈を使用して問題を明確にすることをお勧めします。適切な名詞とキーワードは英語で保持できます。
- コードを変更するときは、コメント、特にパラメーター、戻り値、例外、およびコアロジックの変更に応じて変更する必要があります。
- コードを慎重にコメント化します。単にコメントアウトするのではなく、上記で詳細に説明する必要があります。不要な場合は削除してください。
- コメントの要件：
1）デザインのアイデアとコードロジックを正確に反映できます。
2）他のプログラマーがコードの背後にある情報をすばやく理解できるように、ビジネスの意味を説明できるようにします。まったくコメントのない大きなコードは、読者にとっては天体の本のようなものです。コメントは自分が見るためのものであり、長い間隔があってもそのときの考え方を明確に理解できるはずです。自分の仕事を引き継ぐ。 - 優れた命名とコード構造は自明であり、コメントは簡潔かつ正確であり、適切に表現されるよう努めています。コメントを回避するための極端な1つは、過度のコメントです。これは、コードのロジックが変更されると、コメントの変更がかなりの負担になるためです。
- 特別な注釈マークについては、マークの人物と時間を示してください。これらのマークをタイムリーに処理することに注意を払い、多くの場合、マークスキャンを通じてそのようなマークを処理します。オンライン障害は、これらのマークのコードから発生する場合があります。