前言
本文档反映的是SpringSide 团队的编码规范,同时推荐所有用SpringSide框架的开发h员遵循?/p>
本文档基本遵?span class="nobr">Sun's Coding ConventionsQ补充了其中没有说明或者有所改动的地斏V?br />
本文档随SpringSide的开发而不断更斎ͼ最新版本请讉KSpringSide WikiQ?/font>
http://wiki.springside.org.cn/display/springside/Coding+Standards版权声明
本规范由springside团队l护Q相兌Z意见请发至springside@gmail.comQ{载请注明出处?/p>
规范{说明
- U别I(xin): 默认登记要求所有项目中的所有成员遵守?/font>
- U别I(xin)I: 所有项目中的所有成员遵守?/font>
- U别I(xin)II: ?/font> 励各个项目根据实际情冉|行?/font>
1.格式与命名规?Formating and Naming Conventions)
1.1 ~进
使用Tab~进Q而不是空格键--羃q?Q?Q?字符的选择权留l阅读者?/p>
1.2 换行
每行120字符--因ؓ(f)已是1024*768的年代?/p>
if,for,while语句只有单句Ӟ如果该句可能引v阅读hQ需要用" {"?}"括v来,否则可以省略?/p>
if (condition)
if (condition) doSomething();
else
doSomething();
1.3 命名规则
- 不允怋用汉语拼韛_名?
- 遇到~写如XMLӞ仅首字母大写Q即loadXmlDocument()而不是loadXMLDocument()
- Package名必d部小写,量使用单个单词
- Interface名可以是一个名词或形容?加上'able','ible', or 'er'后缀)Q如RunnableQAccessible?br />ZZ接口~程Q不采用首字母ؓ(f)I或加上IF后缀的命名方式,如IBookDao,BookDaoIF?
- 面部g名徏议命名ؓ(f)QbtnOK、lblName或okBtn、nameLbl?font color="#cc6600">(II)
其中btn、lbl~写代表按钮(Button)、标{?Label)? - 局部变量及(qing)输入参数不要与类成员变量同名(get/setҎ(gu)与构造函数除?
1.4 声明
- 修饰W应该按照如下顺序排列:(x)public, protected, private, abstract, static, final, transient, volatile, synchronized, native, strictfp?
- cM接口的声明顺?可用Eclipse的source->sort members功能自动排列):
- 静态成员变?/ Static Fields
- 静态初始化?/ Static Initializers
- 成员变量 / Fields
- 初始化块 / Initializers
- 构造器 / Constructors
- 静态成员方?/ Static Methods
- 成员Ҏ(gu) / Methods
- 重蝲自Object的方法如toString(), hashCode() 和mainҎ(gu)
- cd(内部c? / Types(Inner Classes)
同等的类型,按public, protected, private的顺序排列?/p>
2.注释规范(Document Convertions)
2.1 注释cd
2.1.1 JavaDoc注释
略?/p>
2.1.2 失效代码注释
?*...*/界定Q标准的C-Style的注释。专用于注释已失效的代码?/p>
* Comment out the code
* String s = "hello";
* System.out.println(s);
*/
2.1.3 代码l节注释
?/界定Q专用于注释代码l节Q即使有多行注释也仍然?/Q以便与?**/注释的失效代码分开
除了U有变量外,不推荐用行末注释?/p>
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 注释的格?/h3>
- 注释中的W一个句子要以(英文Q句受问h者感叹号l束。Javadoc生成工具?x)将注释中的W一个句子放在方法汇总表和烦引中?
- Z在JavaDoc和IDE中能快速链接蟩转到相关联的cMҎ(gu)Q尽量多的用@see xxx.MyClassQ@see xx.MyClass#find(String)?
- Class必须以@author 作者名声明作者,不需要声明@version与@dateQ由版本理pȝ保留此信息?font color="#cc6600">(II)
- 如果注释中有过一个段落,?lt;p>分隔?font color="#cc6600">(II)
- CZ代码?lt;pre></pre>包裹?font color="#cc6600">(II)
- 标识(java keyword, class/method/field/argument名,Constants) ?lt;code></code>包裹?font color="#cc6600">(II)
- 标识在第一ơ出现时以{@linkxxx.Myclass}注解以便JavaDoc与IDE中可以链接?font color="#cc6600">(II)
2.3 注释的内?/h3>
2.3.1 可精的注释内?/h4>
2.3.1 可精的注释内?/h4>
注释中的每一个单词都要有其不可缺的意义Q注释里不写"@param name -名字"q样的废话?br /> 如果该注释是废话Q连同标{ֈ掉它Q而不是自动生成一堆空的标{,如空的@param nameQ空的@return?/p>
2.3.2 推荐的注释内?/h4>
- 对于API函数如果存在契约Q必d明它的前|条?precondition)Q后|条?postcondition)Q及(qing)不变?invariant)?font color="#cc6600">(II)
- 对于调用复杂的API量提供代码CZ?font color="#cc6600">(II)
- 对于已知的Bug需要声明?font color="#cc6600">(II)
- 在本函数中抛出的unchecked exception量用@throws说明?font color="#cc6600">(II)
2.3.3 Null规约
如果Ҏ(gu)允许Null作ؓ(f)参数Q或者允许返回gؓ(f)NullQ必dJavaDoc中说明?br /> 如果没有说明Q方法的调用者不允许使用Null作ؓ(f)参数Qƈ认ؓ(f)q回值是Null Safe的?/p>
* 获取对象.
*
* @ return the object to found or null if not found.
*/
Object get(Integer id){
...
}
2.3.4 Ҏ(gu)代码注释
- 代码质量不好但能正常q行Q或者还没有实现的代码用//TODO: ?//XXX:声明
- 存在错误隐?zhn)的代码?/FIXME:声明
3.~程规范(Programming Conventions)
3.1基本规范
- 当面对不可知的调用者时Q方法需要对输入参数q行校验Q如不符合抛出IllegalArgumentExceptionQ徏议用Spring的Assertpd函数。?
- 隐藏工具cȝ构造器Q确保只有staticҎ(gu)和变量的cM能被构?
- 变量Q参数和q回值定义尽量基于接口而不是具体实现类Q如Map map = new HashMap();
- 代码中不能用System.out.println()Qe.printStackTrace()Q必M用logger打印信息?
3.2 异常处理
- 重新抛出的异常必M留原来的异常Q即throw new NewException("message",e); 而不能写成throw new NewException("message")?
- 在所有异常被捕获且没有重新抛出的地方必须写日志。?
- 如果属于正常异常的空异常处理块必L释说明原因,否则不允许空的catch块?
- 框架量捕获低异常Qƈ装成高U异帔R新抛出,隐藏低异常的细节?font color="#3333ff">(III)
3.3 代码度量
3.3.1 耦合度度?/h4>
- DAC度量g要不大于7 ( III )
解释QDAC(Data Abstraction Coupling)数据抽象耦合度是描述对象之间的耦合度的一U代码度量。DAC度量DCZ个类中有实例化的其它cȝ个数?
- CFO度量g要不大于20 ( III )
解释QCFO(Class Fan Out)cL出是描述cM间的耦合度的一U代码度量。CFO度量DCZ个类依赖的其他类的个数?
3.3.2 Ҏ(gu)度量
解释QDAC(Data Abstraction Coupling)数据抽象耦合度是描述对象之间的耦合度的一U代码度量。DAC度量DCZ个类中有实例化的其它cȝ个数?
解释QCFO(Class Fan Out)cL出是描述cM间的耦合度的一U代码度量。CFO度量DCZ个类依赖的其他类的个数?
太多的方法(构造器Q参数媄响代码可L。考虑用值对象代替这些参数或重新设计?
解释QCC(CyclomaticComplexity)圈复杂度指一个方法的独立路径的数量,可以用一个方法内if,while,do,for,catch,switch,case,?:语句?amp;&,||操作W的M数来度量?/font>
解释QNPath度量DCZ个方法内可能的执行\径的条数。?
3.3.3 其他度量
- 布尔表达式中的布?yu)(dng)运?&&,||)的个C过3?font color="#3333ff">(III)
- if语句的嵌套层?层以?font color="#cc6600">(II)
- 文g长度2000行以?font color="#cc6600">(II)
- 匿名内部c?0行以?( II )
太长的匿名内部类影响代码可读? 重构为命名的Q普通)内部cR?
3.4 JDK5.0
- 重蝲Ҏ(gu)必须使用@OverrideQ可避免父类Ҏ(gu)改变时导致重载函数失效?
- 不需要关心的warning报告用@SuppressWarnings("unused"), @SuppressWarnings("unchecked"),@SuppressWarnings("serial") 注释?
4.自动代码?/h2>
使用Eclipse??Inellij IDEA
的代码校验已经可以排除很多问题?/p>
再配合?span class="nobr">Checkstyle ,PMD
,FindBugs
三重检查,׃层的校验늛了大部分的Guide Line?/p>
如果代码要求不苛刻,可以仅用Eclipse ?IDEA 搭配 Checkstyle的两重保湿效果?/p>
- EclipseQ在Windows->Preferences->Java-Compiler->Errors/Warnings中,按本文档的规则将一些原来Ignore的规则打开?
- IDEAQ在Setting->Errors中设定规则,调用Analyzer->Inspece Codeq行校验?
- CheckStyleQ安?span class="nobr">CheckStyle的Eclipse插g
Q在Windows->Preferences->CheckStyle导入springside团队预设?tools/codereviewer/springside_check.xml的规?
- PMDQ安?span class="nobr">PMD的Eclipse插g
QW(xu)indows->Preferences->PMD清除原来所有规则,导入springside团队预设?tools/codereviewer/springside_pmd.xml的规则?
- FindBugsQ安?span class="nobr">FindBugs的Eclipse插g
Q在目属?>FindBugs中,取消下列警告MS/EI/EI2/ Q SnVI/SE/WS/RS QST/NP/UwF/SS/UuF|UrF|SIC
5.参考资?/h2>- Sun's Coding Conventions
Sun MicroSystemQ?
- The Elements of Java Style
Scott W. Ambler {著Q?
- 代码工L(fng)规则Q?checkstyle
Q?span class="nobr">pmd
Q?span class="nobr">findbugs




