编码规范V10.docx

1、编码规范V10编程规范文档编号：编码规范文档信息：公司级别规范文件文档名称：编程规范文档类别：工程过程 密 级：内部版本信息：1.0建立日期：创 建 人： 审 核 者：批 准 人：批准日期：保 管 人：存放位置：文档修订记录版本编号或者更改记录编号*变化状态简要说明（变更内容和变更范围）日期变更人批准日期批准人10A新增2014-1-15彭毅*变化状态：A增加，M修改，D删除文档审批信息序号审批人角色审批日期签字备注目录1 简介 41.1 目的 41.2 适用范围 41.3 背景描述 41.4 文档结构 42 总则 53 命名规范 63.1 一般命名规范 63.2 特定命名规范 74 文件 9

2、5 语句 115.1 package和import 115.2 类和接口 115.3 类型 125.4 变量 125.5 循环 125.6 条件语句 145.7 其他 146 方法 146.1 方法修饰符 146.2 参数规则 156.3 返回值 156.4 内部实现 167 面向对象高级特性 168 结构和注释 208.1 结构 208.2 注释 219 检查清单 231 简介1.1 目的本文制定的目的是为开发组所有程序员按统一风格、形式编码提供一个标准，从而改进代码的可维护性，提高代码质量。1.2 适用范围本文档的适用范围为：Java编码。1.3 背景描述编码规范对于程序员、整个组织非常的

3、重要： 软件成本的80%来自于维护 几乎没有一个软件从始至终是有一个人维护的 软件规范可以改进代码的可读性，使得程序员能够很快的、彻底的理解新的代码1.4 文档结构该文挡主要分为两部分：Java编程所必须遵守的细则和Java代码审查清单。对于每一条细则包含三项内容：规范细则简单描述、例子和制定该细则的目的和相关背景知识。审查清单列出了根据该编程规范进行代码审查时所要检查的内容。2 总则1) 该规范制定的目标是改进程序的可读性，从而提高程序的可理解性、可维护性，提高代码的质量。从科学的角度来讲，不能期望编码规范涵盖了一种编程语言的方方面面，更多的是具有一种指南、参考的性质，应当允许程序员在编码过

4、程中拥有一定的灵活性。从管理的角度来讲，制定的标准、规范是必须要严格遵守和执行的，不能随意的篡改或者事实上违背组织已经采用的标准和规范。因此，程序员在编码过程中应当完全遵守该规范的所有细则，如果在特定的情况下用某种与该规范细则相冲突的形式更有利于程序的可读性，可以考虑保留这种形式，但必须是在经过正式评审、严格控制的情况下实施的。2) 在规范细则描述过程中，必须、应当和可以具有特定的含义。必须是指必须遵守的细则，应当是指规范推荐的细则，无特殊情况时必须遵守，可以是指规范不禁止但不推荐的细则。不可以是指必须按要求的去做，不应当是指规范不禁止这么做，但无特殊情况还是不要这么做。3 命名规范3.1 一

5、般命名规范3.1.1 名称要求：所有的名称必须用英文书写，不准使用汉语拼音例子：zhengzhi /Must mofity to:earnValue背景：英语是国际化语言3.1.2 包名要求：第一个单词必须小写、第二个单词第一个字母需大写例子：.iscas.intec.entity.pm背景：包名相当于类的命名空间3.1.3 类名要求：名词，不同单词之间不可以用任何其他符号进行分隔，每个单词的第一个字母必须大写例子：Line LineData背景：Java开发的共同约定和Sun核心包的类型命名规范3.1.4 抽象类要求：抽象类命名应当遵守类名的要求。应当在类名前面大写字母Abstract，以明

6、确表示是抽象类。例子：AbstractLine背景：从名字上就看出是抽象类，更加易读。3.1.5 接口要求：接口名称应当遵守类名的要求。应当在接口名前面加上大写字母I，以明确表示是接口。例子：ILine ILineData背景：明确定义是接口，更加易读一点。3.1.6 方法名称要求：方法（构造方法除外）名应当用“动词+名词”、大小写混排的方式命名，起始必须字 符小写，方法名称中对象应当是隐含的。在适当条件下，可以没有名词。例子：boolean isSigned(); void drawLine(); line.getLength(); /Should Not: line.getLineLeng

7、th(); Thread.run(); /Should Not: runThread();背景：Java开发的共同约定和Sun核心包的方法命名规范3.1.7 变量名要求：变量必须用大小写混排的方式命名，起始字符必须小写。成员变量可以用下划线开始例子： Float fWidth；FilePrefix filePrefix； 背景：关于变量命名没有一个可以接受的共同标准，变量的命名遵循如下的原则： 标识符应当直观且可以拼读，可望文知意，不必进行“解码” 标识符的长度应当符合“min-length & max-information”原则 命名规则尽量与所采用的操作系统或开发工具的风格保持一致 程序

8、中不要出现仅靠大小写区分的相似的标识符 程序中不要出现标识符完全相同的局部变量和全局变量，尽管两者的作用域不同而不会发生语法错误，但会使人误解 应当避免名字中出现数字编号，如value1,value2。3.1.8 常量命名要求：应该全部大写，单词间用下划线隔开。static final 是必须的。例子：public static final int MIN_WIDTH = 4;背景：sun java编码规范。3.2 特定命名规范3.2.1 get/set用法要求：成员变量的访问方法应当采用get/set用法，建议采用eclipse的辅助命令生成，尽量不要自己手写。例子：employee.get

9、Name(); matrix.getElement (2, 4); employee.setName (name); matrix.setElement (2, 4, value);isEnabled(); 背景：Java核心包直接访问变量方法的命名规范，在写JavaBean时该规则实际是强制的。3.2.2 is用法要求：在Boolean变量命名和访问方法中应当使用is例子：isSet, isVisible, isFinished, isFound, isOpenboolean isAssigned();背景：Java核心包直接访问变量方法的命名规范，在写JavaBean时该规则实际是强制 的

10、。还可以使用can, has。3.2.3 JFC（Java Swing）变量要求：JFC（Java Swing）变量应当以变量类型作为后缀例子：widthScale, nameJTextField, leftScrollbar, mainJPanel, fileToggle, minLabel背景：通过变量名可以得知变量控件类型，从而增强程序的可读性3.2.4 循环变量要求：方法内部循环变量应当使用i,j,k（数字），c，d（字符） 背景：这是一种习惯、简便用法，内部循环变量的作用域有限，比较容易区分。3.2.5 命名缩写要求：在变量或者方法名称中，应当避免不通用缩写例子：cp instead

11、 of copy pt instead of point comp instead of compute 背景：非通用的缩写会影响程序可读性，对于下面比较通用的词语推荐使用缩写HypertextMarkupLanguage instead of html CentralProcessingUnit instead of cpu3.2.6 否定布尔变量要求：不可以出现否定布尔变量例子：boolean isError; / NOT: isNotError boolean isFound; / NOT: isNotFound背景： 在使用！操作符时，出现双重否定，影响了程序的可读性4 文件4.1.1

12、 行长度要求：列数不可以超过80（Eclipse默认的是80）背景：编程工具缺省的可见和打印宽度，否则不利于程序的可读性4.1.2 缩进要求：4个字符例子：背景：sun java 编码规范，在Eclipse当中默认设置Tab的长度为4个字符：4.1.3 分号要求：for 循环中的分号应与下一个字符间保留一个空格。 例子：if (int i = 0;i 10;i+) / 错误if (int i = 0; i 0) i +; / 错误： 和 在同一行if (i 0) i+； / 正确： 单独作为一行背景：增强代码的可读性4.1.6 小括号要求：在任何时候左括号和后一个字符之间不应该出现空格。同样,

13、 右括号和前一个字符之间也不应该出现空格. 不要在语句中使用无意义的括号. 括号只应该为达到某种目的而出现在源代码中。例子：Integer count = new Integer( sumString ); / 错误Integer count = new Integer(sumString); / 正确if (i) = 42) / 错误：括号毫无意义if （(i = 42) or (j = 42)） / 正确：的确需要括号背景：良好的使用小括号，能增强代码的可读性。4.1.7 操作符要求：操作符（如=、=、!=、+、-、*、/、&、|等）两边必须各保留一个空格，!操作符必须在右边保留一个空格。

14、例子：str=test; / 错误str = test; / 正确：=两边各有一空格 背景：增强代码的可读性4.1.8 分行要求：分行必须明显例子：totalSum = a + b + c + d + e); function (param1, param2, param3); setText (Long line split + into two parts.); for (tableNo = 0; tableNo maxTable; tableNo += tableStep)背景： 当列数超过80行时应当分行显示，为了增强可读性一般在如下符号后进行换行： 逗号 操作符 后一行和前一行的表达

15、式对齐5 语句5.1 package和import5.1.1 包声明要求：包的声明语句必须放在文件开始，每个文件必须属于特定的一个包背景：前者是Java所强制规定的，后者有利于使用Java面向对象的技术5.1.2 import语句要求：import语句应当不允许用.*import一组java类，不能包含多余的java类。例子：import java.io.*; import .*; import java.rmi.* import java.rmi.server.*;背景：通过排序和分组可以比较容易分清楚该类基于那些包构建的。Eclipse使用ctrl+shift+O可以重新组织import。

16、5.2 类和接口5.2.1 类和接口的组织要求：类和接口的声明应当按下列方式组织1. Class/Interface documentation. 2. class or interface statement. 3. Class (static) variables in the order public, protected, package (no access modifier), private. 4. Instance variables in the order public, protected, package (no access modifier), private. 5

17、. Constructors. 6. Methods (对于重载的方法，应该按照参数的多少从少到多进行排序). 背景：比较容易得找到所要的内容5.3 类型5.3.1 类型转换要求：基本类型转换应当明确。例子：floatValue = (float) intValue; / NOT: floatValue = intValue;背景：明确的进行类型转换增强程序的可读性。5.4 变量5.4.1 变量类型声明要求：变量类型应当和变量的含义保持一致。例子：String isPhase /Wrong boolean isPhase /Right背景：影响程序的可读性。5.4.2 局部变量使用要求：变量应

18、当在声明时进行初始化；变量的作用域应当尽可能小。变量应当避免多次赋值。变量如果不使用，必须去除。背景：对于前者由于Java编译时会检测是否进行了初始化，不会因变量未初始化造成错 误，后者有利于程序的可读性5.4.3 类成员变量声明要求：类成员变量应当是私有的。如果不是私有的，必须说明理由。背景：将类成员变量公有化会违反面向对象的信息隐藏和封装规则5.5 循环5.5.1 for初始语句要求：所有迭代循环都使用for语句来做，不用while,do.while等语句。循环控制变量之外的其他变量不可以出现在for初始语句中例子：sum = 0; / NOT: for (i=0, sum=0; i100

19、; i+) for (int i=0; i100; i+)/ sum += valuei; sum += valuei;背景：有利于程序的可读性和可维护性 5.5.2 循环控制变量要求：在循环控制体内不可以修改循环控制变量。背景：导致程序逻辑复杂，带来潜在的问题。5.5.3 do.while语句要求：应当使用for语句代替。背景：dowhile逻辑可以转换为等价的for形式，dowhile语句把判断条件放在后面有损程序的可读性5.5.4 break, continue语句要求：break, continue语句应当慎用背景：break主要用于switch语句，在循环体内不推荐使用break,

20、continue语句，因为它分割了循环基本块，对程序的效率（特别是循环次数比较多）影响比较大。但对下面的情形可以使用break, continuefor(int i = 0; i iRange; i+) /The loop body is executed only one timeif( sItemNamesi.equals(“Target”) /do some operationbreak;while(i iRange) /The loop body isnt executed only under some certain conditionsif( sItemNamesi.equals

21、(“target”)/do some time-consuming operationscontinue;5.5.5 for(;)语句要求：for(;)语句应当代替while(true)语句背景：后者需要测试是否为真且没有任何意义5.6 条件语句5.6.1 判断条件要求：判断条件不可以包含执行语句；复杂判断条件必须避免。如果要做复杂判断，请用单独的方法来表示。例子：file = openFile (fileName, w); / NOT:if (file = openFile (filename.if (file != null) / w) != null) : / : / 背景： 重构，提高

22、代码的可读性。5.6.2 if else语句要求：正常的情形应当放在if部分，异常的部分应当放在else部分例子：boolean isSuccess = readFile (fileName); if (isSuccess) /Normal operations else /Exceptional operations 背景：有利于程序的可读性，符合正常的思维习惯 5.7 其他5.7.1 常数要求：除0,1外的数必须避免在程序中出现背景：Magic Number。在程序中直接写数字，严重影响程序的可读性和可维护性6 方法6.1 方法修饰符要求：方法修饰符应当按如下顺序书写： static ab

23、stract synchronized final native 背景：指public、private、package、protected，指volatile、transient6.2 参数规则6.2.1 参数命名要求：参数名应当完整，缩写应当遵循缩写规则。例子：void setValue(int w, int h); /Not Good Stylevoid setValue(int width,int height); /Good Style背景：有利于程序的可读性6.2.2 参数顺序要求：参数顺序应当合理例子：对于subString函数。一般开始在前，结束在后。 void subStrin

24、g(int beginIndex, int endIndex);背景：符合阅读和思考习惯。6.2.3 参数个数要求：方法的参数个数必须小于等于5。无用的参数必须去掉。背景：方法参数太多不利于调用和理解，容易出错。超过5个需要将参数封装起来。6.3 返回值6.3.1 返回值类型要求：方法名字和返回值的类型不可以冲突例子：int getUserName(); /Bad styleString getUserName(); /Good style 背景：调用方法时容易产生歧义和错误。6.3.2 附加返回值要求：考虑程序的灵活性，可以在不明确需要返回值的情况下返回一个引用例子：StringBuffer

25、.append(String s);背景：可以用于连接操作。6.4 内部实现6.4.1 参数检查要求：方法必须对传进来的参数进行必要的检验。参数是否为null，由方法的调用者来进行保证。对于允许参数为null的情况，必须在方法的JAVADOC中进行说明。对于输入参数的范围有严格要求的话，必须在方法实现中进行检查。背景：提高程序的健壮性6.4.2 方法功能要求：方法的功能应当单一。背景：方法功能过多不利于维护和编写，可能会产生很多副作用。6.4.3 方法规模要求：方法的规模一般应当控制在50行以内（不能超过一屏）背景：便于方法的编写、测试和维护6.4.4 static局部变量要求：方法中不可以出

26、现局部静态变量背景：局部静态变量导致程序具有记忆的功能，程序的状态不可预测6.4.5 异常处理要求：catch语句中必须有异常处理代码，异常不可以被忽略。背景：提高程序的健壮性，防止异常被隐藏、增加调试的难度7 面向对象高级特性7.1.1 私有对象要求：对不可以实例化的类，可以声明私有的缺省构造函数 背景：控制对某些的类的访问7.1.2 Re-inheritance要求：Re-inheritance不可以出现例子：public interface Colorable int RED = 0xff0000, GREEN = 0x00ff00, BLUE = 0x0000ff;public int

27、erface Paintable extends Colorable int MATTE = 0, GLOSSY = 1;class Point int x, y; class ColoredPoint extends Point implements Colorable . . .class PaintedPoint extends ColoredPoint implements Paintable . . . RED . . .背景：re-inheritance不会出现错误，但类间的关系过于晦涩。类之间的关系应当尽量简单。7.1.3 Multi-inheritance要求：变量多继承不可以出现例子：interface Frob float v = 2.0f; class SuperTest int v = 3; class Test extends SuperTest implements Frob public static void main(String args) new Test().printV(); void printV() System.out.println(v); 背景：多重变量继承因为命名冲突不便于程序编写和可读。7.1.4 变量隐藏要求：变量隐藏不可以出现例子：class Point