注釈の規則
1. [必須] クラス、クラス属性、およびクラス メソッドに関するコメントは Javadoc 仕様を使用し、/**コンテンツ*/ 形式を使用する必要があります。// xxx 形式は使用できません。
注: IDE 編集ウィンドウでは、Javadoc モードにより関連するコメントが表示され、生成された Javadoc は対応するコメントを正しく出力できます; IDE では、プロジェクトがメソッドを呼び出すと、メソッドを入力せずにメソッド、パラメータ、戻り値の意味に関するプロンプトにカーソルを合わせると、 読み取り効率が向上します。
2. [必須] すべての抽象メソッド (インターフェイス内のメソッドを含む) は、戻り値、パラメータ、および 例外を除き、Javadoc でコメント化する必要があります。説明に加えて、メソッドが何を行うのか、どのような機能を実装するのかも指摘する必要があります。
注: サブクラスの実装要件や呼び出し上の注意事項について説明してください。
#3. 【必須】すべてのクラスに作成者情報を追加する必要があります。
#4. [必須] メソッド内の単一行コメント、コメントされたステートメントの上に新しい行を開始し、// comment を使用します。メソッド内の複数行のコメント/* */ コメントを使用し、コードと一致するように注意してください。
5. [必須] すべての列挙型フィールドには、各データ項目の目的を説明するコメントが必要です。
6. [推奨] 中途半端な英語でコメントするよりも、中国語のコメントを使って問題をわかりやすく説明したほうがよいでしょう。固有名詞やキーワードは英語の原文の のままでも構いません。
カウンターの例: 「TCP 接続タイムアウト」は「伝送制御プロトコル接続タイムアウト」として解釈され、理解するのがさらに面倒です。
7. [推奨事項] コードを変更する場合、特にパラメーター、戻り値、例外、コア ロジックなどの変更など、それに応じてコメントも変更する必要があります。 。
注: コードと注釈の更新は、道路ネットワークとナビゲーション ソフトウェアの更新が同期していないのと同様に、同期していません。ナビゲーション ソフトウェアの遅れが深刻な場合、移動する能力を失う。
#8. 【参考】 コメントアウトしたコードは、単にコメントアウトするのではなく、できるだけ指示を伴うようにしてください。
注: コードがコメントアウトされる可能性は 2 つあります。 1) このコードのロジックは後で復元されます。 2) 絶対に使用しないでください。前者に発言情報がないと、アノテーションの動機を知ることが困難となる。後者は直接削除することをお勧めします (コード ウェアハウスには履歴コードが保存されます)。
9. [参考] コメントの要件: 第一に、設計アイデアとコード ロジックを正確に反映できること、第二に、他のプログラマーがコードの背後にある情報をすぐに理解できるように、ビジネス上の意味を説明できること。コメントがまったくない大部分のコードは、読者にとってはバイブルのようなものです。コメントは自分が読むためのものです。時間が経っても、当時の考え方がよくわかります。コメントは後任者が読むためのものでもあります。 、それ自体の作業をすぐに引き継ぐことができるようにします。
#10. [参考] 適切な名前付けとコード構造は一目瞭然であり、コメントは簡潔、正確、表現力豊かである必要があります。コメントの極端な
を避ける: コメントが多すぎる、過剰になる コードのロジックを変更すると、コメントを変更するのはかなりの負担になります。
反例:
// put elephant into fridge put(elephant, fridge);メソッド名 put と 2 つの意味のある変数名 elephant と Bridge は、これが何をしているのか、そして言語をすでに説明しています。 明確に定義されたコードには追加のコメントは必要ありません。
#11. 【参考】特別なコメントマークについては、マークした人およびマークした時期を明記してください。これらのマークをタイムリーに処理するよう注意し、マーク スキャンを通じてこのようなマークを頻繁に清掃してください。オンライン障害は、これらのマークのコードに起因する場合があります。
1) To-Do 項目 (TODO): (人物をマーク、時刻をマーク、[推定処理時間])
は、次のことを行う必要があることを示します。実装されていますが、まだ利用できません 未実装の機能。これは実際には Javadoc タグであり、現在の Javadoc はまだ実装されていませんが、すでに広く使用されています。クラス、インターフェース、およびメソッドにのみ適用できます (Javadoc タグであるため)。
2) エラー、動作しません (FIXME): (人物をマーク、時刻をマーク、[推定処理時間])
コメントに FIXME をマークしてください A特定のコードが間違っていて機能しないため、すぐに修正する必要がある状況。
