规范等级说明- 级别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。 - 局部变量及输入参数不要与类成员变量同名(get/set方法与构造函数除外)
1.4 声明- 修饰符应该按照如下顺序排列：public, protected, private, abstract, static, final, transient, volatile, synchronized, native, strictfp。
- 类与接口的声明顺序(可用Eclipse的source->sort members功能自动排列):
- 静态成员变量 / Static Fields
- 静态初始化块 / Static Initializers
- 成员变量 / Fields
- 初始化块 / Initializers
- 构造器 / Constructors
- 静态成员方法 / Static Methods
- 成员方法 / Methods
- 类型(内部类) / 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)
- 如果注释中有超过一个段落，用<p>分隔。(II)
- 示例代码以<pre></pre>包裹。(II)
- 标识(java keyword, class/method/field/argument名，Constants) 以<code></code>包裹。(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)
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:声明
|
|
收藏
淘帖
踩
