代码和注释规范.doc

JAVA编程规范代码和注释规范文档编号版 本1.0JAVA编程规范代码规范注释规范1引言本文档对Java代码的编程方式、风格做了统一规范，目的是减少编程人员代码编写中的语法错误，并通过增强代码的通读性和易懂性，使得代码修改和程序维护相对简单。本文档可用作公司新进人员的培训材料，也可用作检查代码编写质量的参考。2代码规范2.1 缩进缩进必须用 Tab 键。不允许使用 空格 键缩进。每Tab缩进4个空格长度。2.2 页宽页宽设置为80字符，即每行代码不应超过80字符数。注：写在文档中的例子每行的宽度应更短，一般不超过70字符。2.3 折行当一个表达式或一行语句超长时(超出页宽)，必须按以下规则进行折行：l 在逗号之后折行l 在操作符之前折行l 当表达式或语句有多层嵌套时，尽量避免或减少拆开嵌套层次l 折行代码的缩进位置应对齐于前一行的同一嵌套层次l 若沿用以上规则导致代码杂乱或者代码太靠右，就用2个Tab缩进代替这里是一些方法定义和调用的折行例子：someMethod(longExpression1, longExpression2, longExpression3,longExpression4, longExpression5);var = someMethod1(longExpression1,someMethod2(longExpression2,longExpression3);以下是三个算术表达式的折行例子。前两个都是正确的，都避免了括弧表达式被拆开，第三种情况应当避免。longName1 = longName2 * (longName3 + longName4 - longName5)+ 4 * longname6;/正确的longName1 = longName2 * (longName3 + longName4 - longName5)+ 4 * longname6;/正确的longName1 = longName2 * (longName3 + longName4- longName5) + 4 * longname6;/避免的下面是两个方法定义的缩进例子。第一个是规范的例子。第二个例子，如果沿用常规的缩进规范，第二行和第三行将会紧靠右端，左边留白太多，因此用以2个Tab字符替代缩进。/规范的缩进someMethod(int anArg, Object anotherArg, String yetAnotherArg,Object andStillAnother) ./用2个Tab字符来避免缩进过深private static synchronized horkingLongMethodName(int anArg,Object anotherArg, String yetAnotherArg,Object andStillAnother) .对于 if 语句的折行必须用2个Tab缩进。常规的缩进可能导致别扭的代码结构，例如：/不使用这种缩进if (condition1 & condition2)| (condition3 & condition4)|!(condition5 & condition6) /不正确的分行doSomethingAboutIt(); /可能导致此行被忽略/支持使用这种缩进if (condition1 & condition2)| (condition3 & condition4)|!(condition5 & condition6) doSomethingAboutIt();/或者采用这种缩进if (condition1 & condition2) | (condition3 & condition4)|!(condition5 & condition6) doSomethingAboutIt();以下三种三元表达式的格式都可以接受：alpha = (aLongBooleanExpression) ? beta : gamma;alpha = (aLongBooleanExpression) ? beta: gamma;alpha = (aLongBooleanExpression)? beta: gamma;2.4 打印语句程序调试时，打印语句（System.out.println()）必须靠齐代码页左端书写，便于整理代码时去除此调试信息。3注释规范Java程序有两种注释方式：代码注释和文档注释。代码注释类似于C+中的注释，包含在/* */之中或者在/之后。文档注释是Java所特有的doc注释，它以/*开始，到*/结束。文档注释主要是为支持JDK工具javadoc而采用的。Javadoc能识别注释中用标记标识的一些特殊变量，并把doc注释加入它所生成的HTML文件。代码注释可以用来注释掉（屏蔽）代码，也可用来对某一执行语句而作详细的说明。文档注释是指对代码规格的描述，这些与执行无关的说明用来给那些不需要了解和处理源代码的开发者使用。注释不能放在用星号或其它符号画出来的大方框内。注释中不能包含特殊字符，例如制表符和回格符。3.1 代码注释程序中可以有四种代码注释格式：块注释、单行注释、行尾注释和结束行注释。3.1.1 块注释多行文本注释，被用来提供文件、方法、数据结构和算法的详细描述信息。可用在每个文件的开头和每个方法之前。也可以用在其它地方，例如方法体内。当块注释在函数或方法体内使用时，它们必须和其描述的代码在同一级缩进上。块注释前必须有一空行以和其它的代码分隔开。/* * Here is a block comment */3.1.2 单行注释短的注释可以放在一行，和跟随的代码有相同的缩进。如果一个注释不能在一行内写完，则必须使用块注释格式(参考5.1.1节)。一个单行注释前必须有一空行和其它代码分开。这里是一个Java代码的行注释例子：if (condition) /* Handle the condition. */3.1.3 行尾注释非常短的注释可以和其描述的代码写在同一行，但必须和代码分隔的足够开。如果一个代码块中有超过一个以上的行尾注释，它们必须用相同的缩进对齐。例如：if (a = 2) return TRUE;/* special case */ else return isPrime(a);/* works only for odd a */3.1.4 结束行注释注释从/开始，终止于行尾，可以单独一行也可以作为其它行的一部分。不能用做多行文本注释。例：if (foo 1) / Do a double-flip. else return false;/Explain why here.每个函数体、方法体、循环体和if 语句代码过长或者嵌套过深时，必须在结束符后加上/注释。例如：public void doSomething() while (condition) /end while/end doSomething3.1.5 注释代码程序中非物理删除代码时，需要注释掉代码。有三种方式：1需注释代码行数较少时，使用/。例如：/if (bar 1) / / Do a triple-flip./ / else / return false;/2需注释代码行数较多时，使用if (false)。要求if (false)必须靠齐代码页的左端。例如：if (false) 3块注释。使用块注释唯一要注意的是，当被注释的程序段已嵌套有块注释和单行注释时，会产生注释混乱，导致某些语句行脱离注释。3.2 文档注释文档注释描述Jvav类、接口、结构、方法和域。每个文档注释被包含在注释符/*/中，一个类（接口、成员）一个注释。文档注释必须在声明之前：/* * The Example class provides */方法注释必须是以下形式：/* *【方法的处理内容】 *param 【参数名】，【参数说明】 *return 【返回值说明】 *exception 【例外】 */ 方法的处理内容写入方法的处理概要。 参数名，参数説明写入参数变量名和内容。（有复数个时，对复数行描述。复数描述param）（无参数的情况时可省略） 返回值说明写入返回值的内容。（有复数个时，对复数行描述。复数描述return）（没有返回值时可省略） 例外方法描述throw例外的名称。（有复数个时，对复数行描述。复数描述exception）（没有throw例外的场合可省略）