Javaコード仕様-SpringSideチームから
SpringSideコード仕様 前言 このドキュメントはSpringSideチームのコード仕様を反映しており、SpringSideフレームワークを使用するすべての開発者に推奨されています. このドキュメントは、Sun's Coding Conventionsに基本的に従っており、説明や変更がない点を補足しています. 著作権声明 この仕様はspringsideチームが維持し、関連するコメントと意見は[email protected]、転載は出典を明記してください. 仕様等級説明 * レベルI:デフォルトのレベルで、すべてのプロジェクトのすべてのメンバーが遵守する必要があります. * レベルII:すべてのプロジェクトのすべてのメンバーが遵守することを推奨します. * レベルIII:各プロジェクトが実際の状況に応じて実行されることを奨励する. 1.フォーマットとネーミング仕様(Format and Naming Conventions) 1.1インデント スペースキーではなくTabを使用してインデント--2,4,8文字の選択権を読者に残します. 1.2改行 1行120文字--1024*768の年代だからです. if,for,while文が単文のみの場合、その文が読解混同を引き起こす可能性がある場合は、「{」と「}」で囲む必要があります.そうしないと省略できます. //エラー、カッコ{}で囲む必要があります if (condition) if(condition) doSomething(); else doSomething(); 1.3命名規則 * 中国語のピンインによるネーミングは許可されていません * XMLなどの略語に遭遇した場合、loadXMLDocument()ではなくloadXml Document()の頭文字のみが大文字になります. * Package名はすべて小文字でなければなりません.できるだけ単一の単語を使用します. * Interface名は、Runnable、Accessibleなどの名詞または形容詞('able','ible',or'er'接尾辞を加える)であってもよい. インタフェースに基づいてプログラミングするために、IBookDao、BookDaoIFのようなアルファベットIまたはIF接尾辞を加えたネーミング方式は採用されない. * ページ部品名推奨名前は、btnOK、lblNameまたはokBtn、nameLblです.(II) ここで、btn、lblの略はボタン(Button)、ラベル(Label)を表す. * ローカル変数および入力パラメータはクラスメンバー変数と同名にしないでください(get/setメソッドとコンストラクション関数を除く) 1.4宣言 * 修飾子は、public、protected、private、abstract、static、final、transient、volatile、synchronized、native、strictfpの順に並べられるべきです. * クラスとインタフェースの宣言順序(Eclipseのsource->sort members機能で自動的に並べ替えられます): 1.静的メンバー変数/Static Fields 2.静的初期化ブロック/Static Initializers 3.メンバー変数/Fields 4.初期化ブロック/Initializers 5.コンストラクタ/Constructors 6.静的メンバーメソッド/Static Methods 7.メンバーメソッド/Methods 8.toString()、hashCode()およびmainメソッドなどのObjectからの再ロード方法 9.タイプ(内部クラス)/Type(Inner Class) 同等のタイプは、public、protected、privateの順に並べられます. 2.注釈仕様(Document Convertions) 2.1コメントの種類 2.1.1 JavaDocコメント 略. 2.1.2失効コード注記 /*......*/によって定義され、標準的なC-Styleの注釈.アノテーションが無効になったコードに専用です. /* * Comment out the code * String s = "hello"; * System.out.println(s); */ 2.1.3コード詳細コメント //によって定義され、注釈コードの詳細に専用であり、複数行の注釈があっても//を使用して、/**/注釈の失効コードと区別されます. プライベート変数に加えて、行末コメントは推奨されません. class MyClass { private int myField;//An end-line comment. public void myMethod { //a very very long //comment. if (condition1) { //condition1 comment ... } else { //elses condition comment ... } } } 2.2コメントのフォーマット * 注釈の最初の文は(英語)の句点、疑問符、感嘆符で終わります.Javadoc生成ツールは、注釈の最初の文をメソッド要約表とインデックスに配置します. * JavaDocやIDEで関連するクラスやメソッドに素早くリンクしてジャンプできるように、@see xxx.MyClass,@see xx.MyClass#find(String)をできるだけ多く使います. * Classは、@authorの作成者名で作成者を宣言する必要があります.@versionと@dateを宣言する必要はありません.この情報はバージョン管理システムによって保持されます.(II) * コメントに1つ以上の段落がある場合は、
区切る.(II) * サンプルコード
小包.(II)
*タグ(java keyword,class/method/field/argument名,Constants)は、小包として使用されます.(II)
*IDは、JavaDocがIDEにリンクできるように、最初の出現時に{@linkxxx.Myclass}で注記されます.(II)
2.3注釈の内容
2.3.1簡潔な注釈内容
コメントの各単語には欠かせない意味があり、コメントには「@param name-名前」というくだらないことは書かない.
コメントがくだらない場合は、空の@param name、空の@returnなどの空のラベルを自動的に生成するのではなく、ラベルとともに削除します.
2.3.2推奨コメント内容
*API関数に契約がある場合は、その前置条件(precondition)、後置条件(postcondition)、および不変式(invariant)を明記する必要があります.(II)
*複雑なAPIを呼び出す場合は、コードの例をできるだけ提供します.(II)
*既知のBugについては宣言が必要です.(II)
*本関数で投げ出したunchecked exceptionはできるだけ@throwsで説明します.(II)
2.3.3 Null規約
メソッドがNullをパラメータとして許可する場合、または戻り値がNullであることを許可する場合は、JavaDocで説明する必要があります.
説明がなければ,メソッドの呼び出し元はNullをパラメータとして使用することを許さず,戻り値はNull Safeであると考えられる.
/**
*オブジェクトを取得します.
*
* @ return the object to found or null if not found.
*/
Object get(Integer id){
...
}
2.3.4特殊コード注記
*コード品質が悪いが正常に動作していない、またはまだ実現していないコード用//ODO:または//XXX:宣言
*エラーの恐れがあるコード用//FIXME:宣言
3.プログラミング仕様(Programming Conventions)
3.1基本規範
1.不明な呼び出しに直面した場合、IllegalArgumentExceptionが放出された場合、SpringのAssertシリーズ関数を使用することを推奨する入力パラメータを検証する必要があります.
2.ツールクラスのコンストラクタを非表示にし、staticメソッドと変数のクラスのみがインスタンスを構築できないことを確認します.
3.変数、パラメータおよび戻り値の定義は、Mapmap=new HashMap()のような特定の実装クラスではなく、できるだけインタフェースに基づいている.
4.コードにはSystem.out.println()、e.printStackTrace()は使用できません.loggerを使用して情報を印刷する必要があります.
3.2異常処理
1.再放出された例外は、throw new NewException(「message」、e)という元の異常を保持しなければならない.throw new NewException(「message」)と書くことはできない.
2.すべての例外がキャプチャされ、再放出されていない場所にログを書く必要があります.
3.正常異常に属する空の異常処理ブロックが原因を説明しなければならない場合、空のcatchブロックは許可されません.
4.フレームワークはできるだけ低級異常をキャプチャし、高級異常にカプセル化して再放出し、低級異常の詳細を隠す.(III)
3.3コードメジャー
3.3.1結合度メジャー
*DACメトリック値が7(III)以下でないこと
説明:DAC(Data Abstraaction Coupling)データ抽象結合度は、オブジェクト間の結合度を記述するコードメトリックです.DACメトリック値は、クラスにインスタンス化された他のクラスの数を表します.
*CFOメトリック値は20以下(III)
解釈:CFO(Class Fan Out)クラスの扇動はクラス間の結合度を記述するコードメトリックである.CFOメトリック値はクラス依存の他のクラスの個数を表す.
3.3.2メソッドメジャー
*メソッド(コンストラクタ)パラメータが5個以内(II)
多くの方法(コンストラクタ)パラメータがコードの可読性に影響します.これらのパラメータの代わりに値オブジェクトを使用するか、再設計することを考慮します.
*メソッド長さ150行以内(II)
*CCメトリック値が10以下(III)
解釈:CC(CyclomaticComplexity)リングの複雑さは、1つのメソッドの独立したパスの数を指し、if,while,do,for,catch,switch,case,?:文と&,||オペレータの合計数で測定することができる.
*NPathメトリック値200以下(III)
説明:NPathメトリック値は、メソッド内で可能な実行パスの数を表します.
3.3.3その他のメジャー
*ブール式のブール演算子(&,|)の個数は3個を超えない(III)
*if文のネスト層数3層以内(II)
*ファイル長2000行以内(II)
*匿名内部クラス20行以内(II)
長すぎる匿名の内部クラスはコードの可読性に影響し、名前付き(通常)の内部クラスに再構築することを推奨します.
3.4 JDK5.0
1.親メソッドが変更されたときに、リロード関数が無効になることを回避するために、リロードメソッドは@Overrideを使用する必要があります.
2.気にならないwarning情報は@SuppressWarnings("unused"),@SuppressWarnings("unchecked"),@SuppressWarnings("serial")で注記します.
4.自動コードチェック
EclipseとInellij IDEAのコード検証機能を使用すると、多くの問題が排除されています.
Checkstyle,PMD,FindBugsの三重検査を併用し,合計5層の検査はJava符号化の大部分のGuide Lineをカバーした.
要求が厳しくなければ、EclipseやIDEAとCheckstyleを組み合わせた二重保湿効果だけを使うことができます.
1.Eclipse:Windows->Preferences->Java-Compiler->Errors/Warningsで、このドキュメントに従って元のIgnoreのルールをいくつか開きます.
springsideチームを/tools/codereviewer/eclipse.check.prefsの内容をプロジェクトの.setting/org.eclipse.jdt.core.prefsファイルにコピーすることもできます.
2.IDEA:Setting->Errorsでルールを設定し、Analyzer->Inspence Codeを呼び出して検証します.
3.CheckStyle:CheckStyleのEclipseプラグインをインストールし、Windows->Preferences->CheckStyleでspringsideチームが/tools/codereviewer/springside_check.xmlに予め設定したルールをインポートします.
4.PMD:PMDのEclipseプラグインをインストールし、Windows->Preferences->PMDは元のすべてのルールをクリアし、springsideチームが/tools/codereviewer/springside_pmd.xmlにプリセットしたルールをインポートします.
5.FindBugs:FindBugsのEclipseプラグインをインストールし、プロジェクト属性->FindBugsで、以下の警告MS/EI/EI 2/、SnVI/SE/WS/RS、ST/NP/UwF/SS/UuF|UrF|SICをキャンセルします.
5.参考資料
1. Sun's Coding Conventions Sun MicroSystem;
2.The Elements of Java Style Scott W.Amblerなど;
3.コード検出ツールのルール:checkstyle,pmd,findbugs
区切る.(II) * サンプルコード
小包.(II)
*タグ(java keyword,class/method/field/argument名,Constants)は、小包として使用されます.(II)
*IDは、JavaDocがIDEにリンクできるように、最初の出現時に{@linkxxx.Myclass}で注記されます.(II)
2.3注釈の内容
2.3.1簡潔な注釈内容
コメントの各単語には欠かせない意味があり、コメントには「@param name-名前」というくだらないことは書かない.
コメントがくだらない場合は、空の@param name、空の@returnなどの空のラベルを自動的に生成するのではなく、ラベルとともに削除します.
2.3.2推奨コメント内容
*API関数に契約がある場合は、その前置条件(precondition)、後置条件(postcondition)、および不変式(invariant)を明記する必要があります.(II)
*複雑なAPIを呼び出す場合は、コードの例をできるだけ提供します.(II)
*既知のBugについては宣言が必要です.(II)
*本関数で投げ出したunchecked exceptionはできるだけ@throwsで説明します.(II)
2.3.3 Null規約
メソッドがNullをパラメータとして許可する場合、または戻り値がNullであることを許可する場合は、JavaDocで説明する必要があります.
説明がなければ,メソッドの呼び出し元はNullをパラメータとして使用することを許さず,戻り値はNull Safeであると考えられる.
/**
*オブジェクトを取得します.
*
* @ return the object to found or null if not found.
*/
Object get(Integer id){
...
}
2.3.4特殊コード注記
*コード品質が悪いが正常に動作していない、またはまだ実現していないコード用//ODO:または//XXX:宣言
*エラーの恐れがあるコード用//FIXME:宣言
3.プログラミング仕様(Programming Conventions)
3.1基本規範
1.不明な呼び出しに直面した場合、IllegalArgumentExceptionが放出された場合、SpringのAssertシリーズ関数を使用することを推奨する入力パラメータを検証する必要があります.
2.ツールクラスのコンストラクタを非表示にし、staticメソッドと変数のクラスのみがインスタンスを構築できないことを確認します.
3.変数、パラメータおよび戻り値の定義は、Mapmap=new HashMap()のような特定の実装クラスではなく、できるだけインタフェースに基づいている.
4.コードにはSystem.out.println()、e.printStackTrace()は使用できません.loggerを使用して情報を印刷する必要があります.
3.2異常処理
1.再放出された例外は、throw new NewException(「message」、e)という元の異常を保持しなければならない.throw new NewException(「message」)と書くことはできない.
2.すべての例外がキャプチャされ、再放出されていない場所にログを書く必要があります.
3.正常異常に属する空の異常処理ブロックが原因を説明しなければならない場合、空のcatchブロックは許可されません.
4.フレームワークはできるだけ低級異常をキャプチャし、高級異常にカプセル化して再放出し、低級異常の詳細を隠す.(III)
3.3コードメジャー
3.3.1結合度メジャー
*DACメトリック値が7(III)以下でないこと
説明:DAC(Data Abstraaction Coupling)データ抽象結合度は、オブジェクト間の結合度を記述するコードメトリックです.DACメトリック値は、クラスにインスタンス化された他のクラスの数を表します.
*CFOメトリック値は20以下(III)
解釈:CFO(Class Fan Out)クラスの扇動はクラス間の結合度を記述するコードメトリックである.CFOメトリック値はクラス依存の他のクラスの個数を表す.
3.3.2メソッドメジャー
*メソッド(コンストラクタ)パラメータが5個以内(II)
多くの方法(コンストラクタ)パラメータがコードの可読性に影響します.これらのパラメータの代わりに値オブジェクトを使用するか、再設計することを考慮します.
*メソッド長さ150行以内(II)
*CCメトリック値が10以下(III)
解釈:CC(CyclomaticComplexity)リングの複雑さは、1つのメソッドの独立したパスの数を指し、if,while,do,for,catch,switch,case,?:文と&,||オペレータの合計数で測定することができる.
*NPathメトリック値200以下(III)
説明:NPathメトリック値は、メソッド内で可能な実行パスの数を表します.
3.3.3その他のメジャー
*ブール式のブール演算子(&,|)の個数は3個を超えない(III)
*if文のネスト層数3層以内(II)
*ファイル長2000行以内(II)
*匿名内部クラス20行以内(II)
長すぎる匿名の内部クラスはコードの可読性に影響し、名前付き(通常)の内部クラスに再構築することを推奨します.
3.4 JDK5.0
1.親メソッドが変更されたときに、リロード関数が無効になることを回避するために、リロードメソッドは@Overrideを使用する必要があります.
2.気にならないwarning情報は@SuppressWarnings("unused"),@SuppressWarnings("unchecked"),@SuppressWarnings("serial")で注記します.
4.自動コードチェック
EclipseとInellij IDEAのコード検証機能を使用すると、多くの問題が排除されています.
Checkstyle,PMD,FindBugsの三重検査を併用し,合計5層の検査はJava符号化の大部分のGuide Lineをカバーした.
要求が厳しくなければ、EclipseやIDEAとCheckstyleを組み合わせた二重保湿効果だけを使うことができます.
1.Eclipse:Windows->Preferences->Java-Compiler->Errors/Warningsで、このドキュメントに従って元のIgnoreのルールをいくつか開きます.
springsideチームを/tools/codereviewer/eclipse.check.prefsの内容をプロジェクトの.setting/org.eclipse.jdt.core.prefsファイルにコピーすることもできます.
2.IDEA:Setting->Errorsでルールを設定し、Analyzer->Inspence Codeを呼び出して検証します.
3.CheckStyle:CheckStyleのEclipseプラグインをインストールし、Windows->Preferences->CheckStyleでspringsideチームが/tools/codereviewer/springside_check.xmlに予め設定したルールをインポートします.
4.PMD:PMDのEclipseプラグインをインストールし、Windows->Preferences->PMDは元のすべてのルールをクリアし、springsideチームが/tools/codereviewer/springside_pmd.xmlにプリセットしたルールをインポートします.
5.FindBugs:FindBugsのEclipseプラグインをインストールし、プロジェクト属性->FindBugsで、以下の警告MS/EI/EI 2/、SnVI/SE/WS/RS、ST/NP/UwF/SS/UuF|UrF|SICをキャンセルします.
5.参考資料
1. Sun's Coding Conventions Sun MicroSystem;
2.The Elements of Java Style Scott W.Amblerなど;
3.コード検出ツールのルール:checkstyle,pmd,findbugs