Javaコメントまとめ
一、冒頭
プログラム開発の過程で、他の人のコードを変更することがよくあります.この場合、手に持っているコードにはいくつかの状況があります.は筋道があり、分かりやすい. は筋道がなく、分かりやすい. は筋道があり、奥行きがある. は筋道がなく、奥行きがあります.
一般的に言えば、前の2つの幸運に出会って、少なくともコードを閲覧することで、どこを修正する必要があるのか、どのように修正するかを知ることができます.しかし、後の2つの状況、特に4つ目の状況は、絶対に雲の中で霧の中で、自分で書き直す可能性が高い.
これでいくつかの問題が発生しました.はどのように高品質に開発とメンテナンスを行うか. は、コードに最初に接触したときに、このコードの意図と機能を迅速に理解する方法です. 冗長または乱雑なコードを回避する方法.
プログラムにおける注釈はソフトウェア設計者/ソフトウェア開発者とプログラム読書者との間の通信の重要な手段であり、良好な規範と良好な実行規範はソフトウェア自体とソフトウェア開発者にとって特に重要である.ソフトウェアのライフサイクルの中で、良好な注釈はコードの可読性を改善することができて、開発者にできるだけ早く先輩が残したコードを理解させることができます(その中には巧みな可読性の悪いアルゴリズムが使われているものもあります).また、最大限の規範コードを提供し、チームの協力効率を高めることができます.次に、長期にわたって符号化規範に従い、開発者の良好な符号化習慣とより厳格な思考を育成することができる.さらに,敏捷開発思想では注釈をコードに変換する概念も提案されている.
二、Java注釈方法及びフォーマット
1、一方通行注釈(または短い注釈)://...
単行注釈はC++に起源し、1つの"//"で始まり、この行のすべての内容が注釈であることを表す.このタイプの注釈は、書くときに便利だから、もっとよく使われます.キーボードで「/」を探したり、同じキーを2回押すだけで「*」を探したりする必要はありません.また、コメントの最後に終了マークを付ける必要はありません.次の例を示します.
2、ブロックコメント:/*......*/
このような注釈は伝統的なC言語スタイルの注釈であり、1つの「/*」で始まり、その後は注釈内容であり、複数の行を越え、最後に1つの「*/」で終わることができる.このような注釈は、ファイル、方法、データ構造などの意味と用途の説明、またはアルゴリズムの説明を提供するために一般的に使用されるいくつかの行を注釈することができる.一般に1つのファイルまたは1つのメソッドの前に位置し、ブートの役割を果たし、必要に応じて適切な位置に置くこともできます.多くのプログラマーは、連続した注釈の各行に「*」で始まるため、次のような内容をよく見ることができます.
注記:ブロックコメントはHTMLドキュメントには表示されません.次のコメントは上記と変わりません.
3、ドキュメントコメント:/***/
ソフトウェア開発の過程で、プログラムを書く以外に、プログラムのドキュメント化を実現しなければならない.プログラムのドキュメント化では、ドキュメントのメンテナンスが最大の問題です.ドキュメントがコードから分離されると、コードを変更するたびにドキュメントが変更されます.ほとんどの開発者にとっては面倒なことです(コードをせっかく修正したのに、誰がドキュメントを見つけてドキュメントを修正する暇があるのか).最も簡単な解決策は、ドキュメントをコードに「リンク」することです.起きろ.Javaでは、コードとドキュメントを同じファイルに配置するように親切に設計されています.同時に、ドキュメントとコードを整列させるために、特殊な注釈文法を追加し、特殊なドキュメントをマークするために使用します.注釈を抽出して意味のある方法で表現するために、ツールが追加されました(javacということを知っているに違いありません).
ドキュメントのコメントは/***/に書かなければなりません.で、埋め込まれたHTMLまたはドキュメントタグの2つの方法でjavacを使用します.注釈ドキュメントには、注釈の後ろにある要素:クラス、変数、またはメソッドに対応する3種類の注釈ドキュメントがあります.すなわち、1つのクラス注釈はちょうど1つのクラス定義の前に位置する.変数コメントは、変数定義の直前にあります.メソッド定義は、メソッド定義の直前にあります.また、デフォルトではjavacはpublicおよびprotectedメンバーのドキュメントコメントのみを処理し、privateメンバーのコメントは無視できます(-privateタグでprivateメンバーを含めることができます).
1)埋め込みHTML
はHTMLページを描くようにドキュメントを書くことができます.javacは最終的にHTMLページを生成するので、正しいHTMLラベルであれば、すべて使用できます(のようなタイトルラベルを除いて、javacは自分のタイトルを挿入するので、衝突を起こしやすい).以下の例(「Javaプログラミング思想」より抜粋します):
2)@see:他のクラスを参照
このタグを使用すると、他のクラスのドキュメントを参照できます.javacは対応するHTMLを生成し、他のドキュメントに直接リンクします.フォーマットは次のとおりです.
各フォーマットには、生成されたドキュメントにハイパーリンクの「See Also」エントリが自動的に追加されます.(javadocでは、指定したハイパーリンクはチェックされず、有効かどうかは検証されません.)
3)クラス文書タグ
HTMLおよび@see参照の埋め込みに加えて、クラスドキュメントの注釈には、バージョン情報、作成者のタグを含めることもできます.
「バージョン情報」は、バージョンの説明に適した資料を表します.Javadocコマンドラインに「-version」タグを使用すると、生成されたHTMLドキュメントからバージョン情報が抽出されます.
「作成者情報」には、お名前、電子メールアドレス、またはその他の適切な資料が含まれます.Javadocコマンドラインに「-author」タグを使用すると、生成されたHTMLドキュメントから作成者情報が抽出されます.このようなタグは、一連の作成者に複数使用できますが、連続的に配置する必要があります.すべての作成者情報は、最終HTMLコードの個別の段落に一緒に格納されます.
4)変数文書タグ
変数ドキュメントには、埋め込まれたHTMLおよび@see参照のみが含まれます.
5)方法文書タグ
メソッドでは、HTMLおよび@see参照の埋め込みに加えて、パラメータ、戻り値、例外のドキュメントタグを使用できます.
「パラメータ名」はパラメータリスト内の識別子を指し、「説明」は後続の行に続くいくつかの説明文字を表す.新しいドキュメントタグに遭遇すると、前の説明が終了したとみなされます.パラメータごとに1つずつ、任意の数の説明を使用できます.
「説明」は、戻り値の意味です.後ろの行に続くことができます.
「完全クラス名」は、他の場所で定義された例外クラスの名前を明確に指定します.「説明」(同じように次の行に続くことができます)は、この特殊なタイプの例外がメソッド呼び出しに現れる理由を示します.
は@exceptionと同義である.
このタグは、いくつかの古い機能が改良された新しい機能によって置き換えられたことを指摘するために使用される.このタグの役割は、将来の改版時にこの機能を捨てる可能性があるため、ユーザーが特定の機能を使用する必要がないことを提案することです.メソッドを@deprecatedとマークすると、このメソッドを使用するとコンパイラから警告が表示されます.
注:Javaに付いているコメントタグはこれだけではありません.ここでは、比較的よく使われるコメントタグをいくつか紹介します.
三、注釈テクニック-レンガを投げて玉を引く
注記の目的は主に3つあります.コードがきれいです. コードの作用と原理を迅速に理解する. は、文書を形成する.
だからこの2年間の経験に基づいて、いくつかのテクニックをまとめて、レンガを投げて玉を引くことになります.コードに必要な空白行と空白文字を加えて、コードのセグメントを明確にすることができます.注釈に規範的なインデントを提供し、美観を調整します. コードが長い場合または複数のネストされている場合、いくつかの段落の終わりに比較の注釈プロンプトを追加する必要があります. コメントとコメント区切り文字の間にスペースで区切られているので、コメントを見つけやすいです. コメントに枠線を追加しないでください.増加すれば、悪夢の始まりになります. 注釈の長さは80~120文字以下が望ましい.そうしないと、狭い画面で見るのに苦労する. ブロック注釈をコードとするスイッチ: 次のコードで1を印刷します.
次のコードで印刷2
プログラムに2つのコードを切り替える必要がある場合、これは1行目に「/」を追加または削除するだけで便利です.(もちろん、Eclipseではctrl+/)が好きな人が多いです
プログラム開発の過程で、他の人のコードを変更することがよくあります.この場合、手に持っているコードにはいくつかの状況があります.
一般的に言えば、前の2つの幸運に出会って、少なくともコードを閲覧することで、どこを修正する必要があるのか、どのように修正するかを知ることができます.しかし、後の2つの状況、特に4つ目の状況は、絶対に雲の中で霧の中で、自分で書き直す可能性が高い.
これでいくつかの問題が発生しました.
プログラムにおける注釈はソフトウェア設計者/ソフトウェア開発者とプログラム読書者との間の通信の重要な手段であり、良好な規範と良好な実行規範はソフトウェア自体とソフトウェア開発者にとって特に重要である.ソフトウェアのライフサイクルの中で、良好な注釈はコードの可読性を改善することができて、開発者にできるだけ早く先輩が残したコードを理解させることができます(その中には巧みな可読性の悪いアルゴリズムが使われているものもあります).また、最大限の規範コードを提供し、チームの協力効率を高めることができます.次に、長期にわたって符号化規範に従い、開発者の良好な符号化習慣とより厳格な思考を育成することができる.さらに,敏捷開発思想では注釈をコードに変換する概念も提案されている.
二、Java注釈方法及びフォーマット
1、一方通行注釈(または短い注釈)://...
単行注釈はC++に起源し、1つの"//"で始まり、この行のすべての内容が注釈であることを表す.このタイプの注釈は、書くときに便利だから、もっとよく使われます.キーボードで「/」を探したり、同じキーを2回押すだけで「*」を探したりする必要はありません.また、コメントの最後に終了マークを付ける必要はありません.次の例を示します.
// 2、ブロックコメント:/*......*/
このような注釈は伝統的なC言語スタイルの注釈であり、1つの「/*」で始まり、その後は注釈内容であり、複数の行を越え、最後に1つの「*/」で終わることができる.このような注釈は、ファイル、方法、データ構造などの意味と用途の説明、またはアルゴリズムの説明を提供するために一般的に使用されるいくつかの行を注釈することができる.一般に1つのファイルまたは1つのメソッドの前に位置し、ブートの役割を果たし、必要に応じて適切な位置に置くこともできます.多くのプログラマーは、連続した注釈の各行に「*」で始まるため、次のような内容をよく見ることができます.
/*
*
* ，
* 。
*/
注記:ブロックコメントはHTMLドキュメントには表示されません.次のコメントは上記と変わりません.
/* ，
。*/
3、ドキュメントコメント:/***/
/**
*
*/
ソフトウェア開発の過程で、プログラムを書く以外に、プログラムのドキュメント化を実現しなければならない.プログラムのドキュメント化では、ドキュメントのメンテナンスが最大の問題です.ドキュメントがコードから分離されると、コードを変更するたびにドキュメントが変更されます.ほとんどの開発者にとっては面倒なことです(コードをせっかく修正したのに、誰がドキュメントを見つけてドキュメントを修正する暇があるのか).最も簡単な解決策は、ドキュメントをコードに「リンク」することです.起きろ.Javaでは、コードとドキュメントを同じファイルに配置するように親切に設計されています.同時に、ドキュメントとコードを整列させるために、特殊な注釈文法を追加し、特殊なドキュメントをマークするために使用します.注釈を抽出して意味のある方法で表現するために、ツールが追加されました(javacということを知っているに違いありません).
ドキュメントのコメントは/***/に書かなければなりません.で、埋め込まれたHTMLまたはドキュメントタグの2つの方法でjavacを使用します.注釈ドキュメントには、注釈の後ろにある要素:クラス、変数、またはメソッドに対応する3種類の注釈ドキュメントがあります.すなわち、1つのクラス注釈はちょうど1つのクラス定義の前に位置する.変数コメントは、変数定義の直前にあります.メソッド定義は、メソッド定義の直前にあります.また、デフォルトではjavacはpublicおよびprotectedメンバーのドキュメントコメントのみを処理し、privateメンバーのコメントは無視できます(-privateタグでprivateメンバーを含めることができます).
1)埋め込みHTML
はHTMLページを描くようにドキュメントを書くことができます.javacは最終的にHTMLページを生成するので、正しいHTMLラベルであれば、すべて使用できます(
/**
* <pre>
* System.out.println(new Date());
* </pre>
*
* <em> </em> ：
* <ol>
* <li>
* <li>
* <li>
* </ol>
*/
2)@see:他のクラスを参照
このタグを使用すると、他のクラスのドキュメントを参照できます.javacは対応するHTMLを生成し、他のドキュメントに直接リンクします.フォーマットは次のとおりです.
@see
@see
@see #
各フォーマットには、生成されたドキュメントにハイパーリンクの「See Also」エントリが自動的に追加されます.(javadocでは、指定したハイパーリンクはチェックされず、有効かどうかは検証されません.)
3)クラス文書タグ
HTMLおよび@see参照の埋め込みに加えて、クラスドキュメントの注釈には、バージョン情報、作成者のタグを含めることもできます.
@version 「バージョン情報」は、バージョンの説明に適した資料を表します.Javadocコマンドラインに「-version」タグを使用すると、生成されたHTMLドキュメントからバージョン情報が抽出されます.
@author 「作成者情報」には、お名前、電子メールアドレス、またはその他の適切な資料が含まれます.Javadocコマンドラインに「-author」タグを使用すると、生成されたHTMLドキュメントから作成者情報が抽出されます.このようなタグは、一連の作成者に複数使用できますが、連続的に配置する必要があります.すべての作成者情報は、最終HTMLコードの個別の段落に一緒に格納されます.
4)変数文書タグ
変数ドキュメントには、埋め込まれたHTMLおよび@see参照のみが含まれます.
5)方法文書タグ
メソッドでは、HTMLおよび@see参照の埋め込みに加えて、パラメータ、戻り値、例外のドキュメントタグを使用できます.
@param 「パラメータ名」はパラメータリスト内の識別子を指し、「説明」は後続の行に続くいくつかの説明文字を表す.新しいドキュメントタグに遭遇すると、前の説明が終了したとみなされます.パラメータごとに1つずつ、任意の数の説明を使用できます.
@return 「説明」は、戻り値の意味です.後ろの行に続くことができます.
@exception 「完全クラス名」は、他の場所で定義された例外クラスの名前を明確に指定します.「説明」(同じように次の行に続くことができます)は、この特殊なタイプの例外がメソッド呼び出しに現れる理由を示します.
@throws は@exceptionと同義である.
@deprecatedこのタグは、いくつかの古い機能が改良された新しい機能によって置き換えられたことを指摘するために使用される.このタグの役割は、将来の改版時にこの機能を捨てる可能性があるため、ユーザーが特定の機能を使用する必要がないことを提案することです.メソッドを@deprecatedとマークすると、このメソッドを使用するとコンパイラから警告が表示されます.
注:Javaに付いているコメントタグはこれだけではありません.ここでは、比較的よく使われるコメントタグをいくつか紹介します.
三、注釈テクニック-レンガを投げて玉を引く
注記の目的は主に3つあります.
だからこの2年間の経験に基づいて、いくつかのテクニックをまとめて、レンガを投げて玉を引くことになります.
//*
System.out.println(1);
/*/
System.out.println(2);
//*/
次のコードで印刷2
/*
System.out.println(1);
/*/
System.out.println(2);
//*/
プログラムに2つのコードを切り替える必要がある場合、これは1行目に「/」を追加または削除するだけで便利です.(もちろん、Eclipseではctrl+/)が好きな人が多いです