`

Java代码规范-来自SpringSide团队

    博客分类:
  • java
阅读更多

SpringSide代码规范 
前言 

本文档反映的是SpringSide 团队的编码规范,同时推荐所有使用SpringSide框架的开发人员遵循。 

本文档基本遵循Sun's Coding Conventions,补充了其中没有说明或者有所改动的地方。 
版权声明 

本规范由springside团队维护,相关评论与意见请发至springside@gmail.com,转载请注明出处。 
规范等级说明 

* 级别I: 默认级别,要求所有项目中的所有成员遵守。 
* 级别II: 建议所有项目中的所有成员遵守。 
* 级别III: 鼓励各个项目根据实际情况执行。 

1.格式与命名规范(Formating and Naming Conventions) 
1.1 缩进 

使用Tab缩进,而不是空格键--将缩进2,4,8字符的选择权留给阅读者。 
1.2 换行 

每行120字符--因为已是1024*768的年代。 

if,for,while语句只有单句时,如果该句可能引起阅读混淆,需要用" {"和"}"括起来,否则可以省略。 

//错误,需要使用花括号{}括起来 
if (condition) 
if(condition) doSomething(); 
else 
doSomething(); 

1.3 命名规则 

* 不允许使用汉语拼音命名 
* 遇到缩写如XML时,仅首字母大写,即loadXmlDocument()而不是loadXMLDocument() 
* Package名必须全部小写,尽量使用单个单词 
* Interface名可以是一个名词或形容词(加上'able','ible', or 'er'后缀),如Runnable,Accessible。 
为了基于接口编程,不采用首字母为I或加上IF后缀的命名方式,如IBookDao,BookDaoIF。 
* 页面部件名建议命名为: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. 重载自Object的方法如toString(), hashCode() 和main方法 
9. 类型(内部类) / Types(Inner Classes) 

同等的类型,按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) 
* 如果注释中有超过一个段落,用

分隔。(II) 
* 示例代码以


包裹。(II) 
* 标识(java keyword, class/method/field/argument名,Constants) 以包裹。(II) 
* 标识在第一次出现时以{@linkxxx.Myclass}注解以便JavaDoc与IDE中可以链接。(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 特殊代码注释 

* 代码质量不好但能正常运行,或者还没有实现的代码用//TODO: 或 //XXX:声明 
* 存在错误隐患的代码用//FIXME:声明 

3.编程规范(Programming Conventions) 
3.1基本规范 

1. 当面对不可知的调用者时,方法需要对输入参数进行校验,如不符合抛出IllegalArgumentException,建议使用Spring的Assert系列函数。 
2. 隐藏工具类的构造器,确保只有static方法和变量的类不能被构造实例。 
3. 变量,参数和返回值定义尽量基于接口而不是具体实现类,如Map map = 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 Abstraction Coupling)数据抽象耦合度是描述对象之间的耦合度的一种代码度量。DAC度量值表示一个类中有实例化的其它类的个数。 
* CFO度量值不要不大于20 ( III ) 
解释:CFO(Class Fan Out)类扇出是描述类之间的耦合度的一种代码度量。CFO度量值表示一个类依赖的其他类的个数。 

3.3.2 方法度量 

* 方法(构造器)参数在5个以内 ( II ) 
太多的方法(构造器)参数影响代码可读性。考虑用值对象代替这些参数或重新设计。 
* 方法长度150行以内 ( II ) 
* CC 度量值不大于10(III ) 
解释:CC(CyclomaticComplexity)圈复杂度指一个方法的独立路径的数量,可以用一个方法内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三重检查,总共五层的校验涵盖了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->Inspece 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/EI2/ , 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

分享到:
评论

相关推荐

    有springside4.2.3-GA.jar 包

    1. **代码规范**:SpringSide遵循一系列编码和设计规范,帮助团队保持代码一致性,提升代码质量。 2. **自动化配置**:基于Spring的自动化配置,减少了手动配置的工作量,使开发者能更专注于业务逻辑。 3. **最佳...

    springside-core-4.2.2.GA相关jar包

    4. **代码规范和最佳实践**:SpringSide强调代码质量,提供了统一的编码风格和最佳实践,这有助于保持团队间的代码一致性,并提高代码可读性和维护性。 5. **项目模板**:SpringSide通常包含一系列预定义的项目模板...

    SpringSide 团队的编码规范

    SpringSide团队的编码规范是一份详细指导,旨在为使用SpringSide框架的开发者提供一致性和可读性的代码编写标准。这份规范主要基于Sun's Coding Conventions,并对其进行了补充和更新,以适应现代Java开发的需求。 ...

    springside-core-4.1.0.GA.jar

    3. **配置管理**:通过提供统一的配置管理,Springside使得配置文件的组织和管理更加规范,降低了因配置问题导致的错误。 4. **依赖注入**:作为Spring框架的扩展,Springside充分利用了Spring的依赖注入特性,使得...

    springside-springside4-1dff3fc.zip

    3. **Hibernate ORM**:Hibernate是一个对象关系映射(ORM)工具,它允许开发者用Java对象来操作数据库,降低了SQL与Java代码之间的耦合度。在SpringSide 4中,Hibernate作为数据持久层的主力,通过实体类和映射文件...

    springside3-core-3.0.4 源码

    9. **代码规范**:源码遵循了一套统一的编码规范,这对于团队协作和代码质量的提升至关重要,我们可以从中学习如何制定和遵循良好的编码习惯。 10. **文档注释**:springside3-core-3.0.4的源码有详尽的Javadoc注释...

    springside.jar

    从项目构建、测试到功能实现,springside.jar都为Java开发者提供了高效、规范的解决方案。在实际开发中,合理利用springside.jar,不仅能提升开发效率,还能保证代码质量和项目稳定性。因此,理解和掌握springside....

    springside-core-4.2.2.GA

    它推荐的目录结构、命名规范和代码风格,有助于提升代码质量和团队协作效率。 六、实战应用 在实际项目中,SpringSide可以帮助开发者快速搭建项目结构,提供标准的依赖注入和AOP实现。例如,通过SpringSide的...

    springside4-4.2.3.GA

    SpringSide项目的核心理念是提供一套简洁、规范的项目结构和代码模板,让开发者能够快速地开始新项目的开发。在SpringSide4中,主要包含以下几个关键知识点: 1. **Spring框架集成**:SpringSide深度整合了Spring ...

    springside

    2. **最佳实践**:SpringSide定义了一套开发规范,包括命名规则、代码风格、测试策略等,有助于提升团队间的协作效率和代码质量。 3. **示例代码**:SpringSide提供了丰富的示例代码,涵盖了Spring Framework的各种...

    springside开发全面讲解

    3. **代码规范**:springside遵循Java编码最佳实践,如使用Checkstyle和FindBugs进行代码质量检查,确保代码风格统一且无明显错误。 4. **自动化构建**:利用Gradle或Maven的插件,springside支持自动构建、测试和...

    springside3源码及jar

    总结,springside3是一个优秀的Java开发工具,它不仅提供了便捷的开发环境,还有助于提升团队的开发规范。通过深入理解springside3的源码,开发者能够更好地掌握Spring框架的应用技巧,提高开发效率。而jar包的使用...

    springside3 完整项目实例

    - **遵循最佳编码规范**:SpringSide3 强调代码的整洁性和可读性,遵循 Java 编程规范和注释标准。 - **文档编写**:学习如何编写清晰的项目文档,包括需求文档、设计文档和用户手册,以便团队协作和后期维护。 -...

    springside3.0.1.zip

    通过对SpringSide 3.0.1源代码的深入研究,不仅可以加深对Spring框架的理解,还能了解到现代Java企业级开发的各种最佳实践和工具使用。这是一次难得的学习和提升技术的机会,对于任何想要成为专业Java开发者的人来说...

    SpringSide 项目源码

    SpringSide 是一个开源项目,旨在为 Java 开发者提供一个现代化、规范化的 Spring 应用程序开发框架。它基于 Spring Framework,结合了最佳实践和设计模式,使得开发高质量的 Java 应用更加便捷。本项目源码经过测试...

    springside的一个应用实例

    SpringSide是基于Spring框架的一个轻量级、模块化、规范化的开发工具集,旨在提供一种快速、高效且易于维护的Java Web开发模式。在这个实例中,我们将深入探讨如何利用SpringSide进行实际项目开发,特别是其在构建...

    springSide使用手册

    SpringSide 是一个基于 Maven 构建的 Java 企业级应用开发框架,它的核心目标是提供一个规范化的项目结构和最佳实践,帮助开发者快速地搭建起符合现代企业开发标准的项目。SpringSide 使用 Maven 的 Archetype 插件...

    springside4

    SpringSide4是一个基于Spring框架的开源项目,旨在为Java开发者提供一套简洁、规范的项目构建模板和最佳实践。它将Spring的复杂性进行了封装,使得开发者能够更加专注于业务逻辑,提高开发效率。在SpringSide4中,...

    springside_4jar.rar

    SpringSide 4提供了一套经过实践验证的最佳实践,包括代码组织、命名规范、注释规则等,这有助于提升代码质量和团队协作效率。开发者可以通过研究源码,学习如何在实际项目中应用这些最佳实践。 6. **示例项目** ...

Global site tag (gtag.js) - Google Analytics