Java 编程规范v1.00


Java 编程规范编程规范编程规范编程规范 第 1.00 版 二二二二○○○○○○○○七七七七年十一月年十一月年十一月年十一月 Java编程规范 ii 版本控制信息 版本版本版本版本 日期日期日期日期 拟稿和修改拟稿和修改拟稿和修改拟稿和修改 说明说明说明说明 1.00 2007-11-16 陈大鹏 本文档中的所有内容为上海华腾软件系统有限公司的机密和专属所有。未经上海华腾软件系 统有限公司的明确书面许可,任何组织或个人不得以任何目的、任何形式及任何手段复制或 传播本文档部分或全部内容。 Java编程规范 iii 目录目录目录目录 1 源文件源文件源文件源文件 ............................................................................................................................................. 1 1.1 源文件命名 ...................................................................................................................... 1 1.2 源文件的组织 .................................................................................................................. 1 1.3 COPYRIGHT / ID 块的注释 .............................................................................................. 1 1.4 PACKAGE DECLARATION ................................................................................................... 2 1.5 IMPORT DECLARATION ...................................................................................................... 2 1.6 CLASS/INTERFACE 的声明 ................................................................................................ 2 2 命名约定命名约定命名约定命名约定 .......................................................................................................................................... 2 2.1 PACKAGE 命名 .................................................................................................................. 2 2.2 CLASS/INTERFACE 的命名 ................................................................................................ 3 2.3 域(FIELD)命名 ( 局部变量命名 ) ...................................................................................... 3 2.4 方法命名 .......................................................................................................................... 4 2.5 声明的标签命名 .............................................................................................................. 4 3 空格和空行的使用空格和空行的使用空格和空行的使用空格和空行的使用 .......................................................................................................................... 4 3.1 空行 .................................................................................................................................. 4 3.2 空格 .................................................................................................................................. 5 3.3 缩进和续行 ...................................................................................................................... 6 4 注释注释注释注释 ................................................................................................................................................. 6 4.1 通用规则和定义 .............................................................................................................. 6 4.2 文本注释 .......................................................................................................................... 7 4.3 块注释 .............................................................................................................................. 8 4.4 单行注释 .......................................................................................................................... 8 5 类类类类 ..................................................................................................................................................... 8 5.1 定义规则 .......................................................................................................................... 8 5.2 类体组织 .......................................................................................................................... 8 5.3 方法定义 ........................................................................................................................ 10 5.4 本地内部类和匿名内部类 ............................................................................................ 11 5.5 匿名数组表达式和数组初始化 .................................................................................... 11 5.6 接口 ................................................................................................................................ 12 6 声明声明声明声明 ............................................................................................................................................... 12 6.1 简单声明 ........................................................................................................................ 12 6.2 复杂声明 ........................................................................................................................ 13 Java编程规范 1 1 源文件源文件源文件源文件 1.1 源文件命名源文件命名源文件命名源文件命名 Java 源文件的命名格式: ClassOrInterfaceName.java 1.2 源文件的源文件的源文件的源文件的组织组织组织组织 Java 源程序应该包含下列元素,在下列顺序: 1. Copyright/ID block comment 2. package declaration 3. import declaration 4. one or more class/interface declaration 不同的元素之间至少应该有一空行。 1.3 Copyright / ID 块的注释块的注释块的注释块的注释 每个源文件应该以 Copyright/ID 块注释开始,内容包括版本信息和一个标准的版权告示, 版本信息的格式: @(#) module version date [firstname lastname] module :源文件名 version: 版本管理系统中的文件版本 date: 最近修改的日期 firstname lastname:(可选项) 题目在以 SCCS 管理的版本控制系统中,版本信息能通过使用 %W% %E% 而自动更新。 标准的版权告示至少应该包括下面一行: Copyright (c) yearlist CopyrightHolder. All Rights Reserved. yearlist: 一个年份 、年份的范围或以逗号分隔的年份列表 一个例子: /* * @(#) CodingStyleExample.java 1.0 2003/02/23 du_cloud * * Copyright (c) 2003 Huateng. All Rights Reserved. */ Java编程规范 2 1.4 Package declaration 每个源文件应该包含一个 package 的声明。Package 应该从第一列开始,package 名和 package 之间以一空格分开,应由小写字母和“.”组成 如:: package java.lang 建议按公司立项产品名组织 package 名,如: package com.huateng.yinlian 1.5 Import declaration import 声明应从第一列开始,和名字间以一个空格分开,并以 package 名分组,各组间以一 空行分隔.组内部的 import 声明应按照字母排序。如: import java.applet.Applet; import java.awt.Point; 在 import 声明中不主张用通配符。如: import java.util.* 1.6 Class/interface 的声明的声明的声明的声明 class/interface 的声明在 import 声明之后,这些定义在源文件中应尽量少;最多只能有 一个 public 类型的声明,且该声明要放于所有 class/interface 之前。 在 public 声明前应该有一段文档注释,描述其功能和参数(用@param 为标志),要尽量简 要。如: /** * Compute the total distance between a set of Points. *@param starshipCoordinates the locations of all know *@return the total distance */ 非 public 的声明也应该有简单的功能性说明。 2 命名约定 2.1 Package 命名命名命名命名 package 的命名应该用小写字母和数字,没有下划线。如: java.lang java.awt.image Java编程规范 3 如果 package 向外发布,命名必须惟一。建议用 internet 域名的反方向前缀构成法命名, 如: com.huateng.yinlian 2.2 Class/interface 的命名的命名的命名的命名 应该以首字母大写、后续单词首字母大写,也包括只取首字母的缩写词,其他字符均小写, 不要用下划线将字母分开,class 命名应该用名词或名词词组。interface 的命名应该以易读为 目的,如果该 interface 的目的是为了赋予某一对象以特殊的 capability,那么就应该以描述 capability 的形容词来命名。如: Searchable,Sortable,NetwokAccessible 否则用名词或名词词组。 例如: //GOOD type names; LayoutManage,AWTException ArrayIndexOutOfBoundException //BAD type names; ManageLayout awtException array_index_out_of_bounds_exception 2.3 域域域域(field) 命名命名命名命名 ( 局部变量命名局部变量命名局部变量命名局部变量命名 ) 非常数命名(参数类型或非 final 类型)应该以首字母小写、后续单词首字母大写,也包 括只取首字母的缩写词,其他字符均小写,不要用下划线将单词分开,命名应该用名词或名词 词组。例如: char recordDelimiter; 作为常量的域命名应该全大写,用下划线分隔不同的单词。如: MIN_VALUE,MAX_BUFFER_SIZE,OPTION_FILE_NAME 单字符域名应该避免,除临时变量和循环变量。在这种情况下原则是: b for a byte c for a char d for a double e for an Exception object f for a float g for a Graphics object i,j,k,m,n for integers p,q,r,s for String,StringBuffer,or char[] objects 还有一种例外就是 X 和 Y 表示屏幕坐标。避免变量小写 “l”,因为其在一些打印机打印和显 Java编程规范 4 示时和 “1”很难分清。 2.4 方法命名方法命名方法命名方法命名 方法命名应该以首字母小写、后续单词首字母大写,也包括只取首字母的缩写词;其他字 符均小写;不要用下划线将单词分开;命名应该用及物动词或动词词组。如: //GOOD method names: showStatus(),drawCircle(),addLayoutComponet() //Bad method names: mouseButton(),DrawCirle(),serverRunning() 方法中要获得或设置一些类的属性时,应该写成 getProperty() 或 setProperty(),如: getHeight(),setHeight() 当方法之目的是测试类的 boolean 属性时,应该写成:isProperty(),如: isResizable(),isVisible() 2.5 声明的标签命名声明的标签命名声明的标签命名声明的标签命名 声明的标签是 break 或 continue 语句的执行目标。命名全用小写,单词间用下划线分开。 在同一个方法中只能有一个同名的声明标签。声明是被封装在括号 “{}”中,标签本身行缩进 4 个 blank spaces、后跟冒号、单 blank space、”{“,在”}“后面应该有同名标签的注释。格式: statement-label: { } //statement-label 例如: for (int I = 0; i < n; i++) { search: { for (int j = 0; j < n/2; j++) { if (node[j].name == name) break search; } for (int j = n/2; j < n; j++) { if (node[j].name == name) break search; } } //search } 3 空格和空行的使用空格和空行的使用空格和空行的使用空格和空行的使用 3.1 空行空行空行空行 将代码按照逻辑关联分组,组之间以空行分开可以提高可读性。在下列情况下也应该用空 Java编程规范 5 行: 1. 在版权块的注释后、package 声明后、import 段的声明后。 2. 在两个类声明之间。 3. 在两个方法声明之间。 4. 在类内的最后一个域定义和第一个方法声明之间。 5. 在一个块或单行注释前,除非它们是块中的第一行。 3.2 空格空格空格空格 单空格(非 tab)使用的情况: 1. 在一个关键字和开圆括号之间。这适用于下列关键字: catch,for,if,switch,synchronized,while。 2. 不适用于关键字 super 和 this;它们也决不跟空格。 3. 在一些带参数的关键字后。如:return true。 4. 在两个相邻的关键字之间。 5. 在一个关键字或闭圆括号与一开大括号之间(“{”}。 6. 在 and 之前,二进制操作符之后除“.”(dot)之外。注意 instanceof 是二进制操作符: if (obj instanceof Button) { //RIGHT if (obh instanceof(Button)) { //WRONG 7. 在一个列表的逗号之后。 8. 在 for 语句中的分号之后,例如: for (expr1; expr2; expr3) {。 不应该用单空格的情况: 1. 在方法名和其开圆括号之间。 2. 在“.”(dot)操作符的之前或之后。 3. 在一元运算符和操作数之间。 4. 在一个类型转换和转换表达式之间。 5. 在开圆括号之后或闭圆括号之前。 6. 在开方括号“[”之后或闭方括号“]”之前。 如: a += c[I + j] + (int)d + foo(bar(I + j), e); a = (a + b) / (c * d); if (((X + Y) > (Z + W)) || (a != (b + 3))) { return foo.distance(X, Y); } Java编程规范 6 3.3 缩进和续行缩进和续行缩进和续行缩进和续行 行缩进总是四个空格。 代码行被限制在 80 列(对于非 ASCⅡ来说并非 80 个字节)。超过 80 列应划分成一个或多个 续行,续行之间应该对齐,行缩进从第一个续行开始。缩进的多少依赖于声明(statement)的 类型。 如果声明在圆括号的表达式中间续行,如,复杂声明和参数列表的方法,续行应该和第一 行左括号的第一个字符对齐。其他的情况,续行应该保持标准的缩进 4 个空格。如果下一声明 的缩进和前一声明的缩进相同,那么在开大括号后应有一空行,以避免混淆。 例如: //RIGHT foo (long expression1, long_expression2, long_expression3, long_expression4); //RIGHT foo (long_expression1, long_expression2, long_expression3, long_expression4); //RIGHT – blank line follows continuation line because same indent if (long_logical_test_1 || long_logical_test_2 || long_logical_test_3) { statements; } 续行不能以二进制操作符打头;不要在没有空格出现的地方断行,如,在方法名和其开括 号之间;不能在开括号 “{”之前断行,如: //WRONG while (long_expr1 || long_expr2 || long_expr3) { } //RIGHT while (long_expr1 || long_expr2 || long_expr3) { } 4 注释注释注释注释 4.1 通用规则和定义通用规则和定义通用规则和定义通用规则和定义 JAVA 支持文本注释、块注释和单行注释,其原则是: 1. 应该有助于读者理解代码,尤其是那些容易混淆和模糊的地方; Java编程规范 7 2. 避免对代码本身描述的注释,如: i = i + i ; //Add one to i 3. 误导的注释比没注释更糟; 4. 避免注释中有可能过期的相关信息; 5. 避免注释被星号和其他想象的符号包围; 6. 以后要改变或修改的临时注释要有特殊标记,便于以后查找,如: // XXX :Change this to call sort() when the bugs // in it are fixed List->mySort(); 4.2 文本注释文本注释文本注释文本注释 文本注释应该在定义的实体之前,他们之间没有空行。注释的第一行应该是/**,没其他内 容。但应该与下面的定义实体对齐。接下来行的行首包含一个星号,后跟一空格,再后是注释 内容,且应和第一行的星号对齐。第一行的注释是注释本身的小结,注释文本中的句号后应该 是一空格、TAB 或新的一行,注释文本中可以插入 HTML 标记,除标记:

,

,

,

,

,
,
外。 标志的使用: 1. 类和接口注释可能按顺序用到标志: @version,@auther, @see,如有多作者用@auther 分开; 2. 构造函数注释可能按顺序用到标志: @param,@exception,@see 3. 方法注释可能按顺序用到标志: @param,@return,@exception,@see 4. 变量注释只能用标志: @see 文本注释以字符*/结尾,为了有助于辨别也可以用**/。 一个方法示例: /** * Checks a object for “coolness ”. Performs a comprehensive * coolness analysis on the object. …..in its own right. * * @param obj the object to check for coolness * @return true if the object is cool; false otherwise. * @exception OutOfMemoryError If there is not enough memory to * determine coolness. * @exception SecurityException If the security manager cannot be * created * @see isUncool **/ public boolean isCool(Object obj, String name) Java编程规范 8 throws OutOfMemoryError, SecurityException { 4.3 块注释块注释块注释块注释 常规的块注释和传统的 C 语言注释相同,以字符/*开始以*/结束。见 1.3 ,过去常用于注 销几行代码。由于 JAVA 的特殊性,因此,这种用法被禁止。 4.4 单行注释单行注释单行注释单行注释 单行注释包含字符//,其后跟注释内容,之间有一空格。单行注释和其代码行保持对齐(同 样的缩进)。多于一行的注释应该形成一注释组。注释前应有一空行,除非其是第一行。如果注 释用于以下的几个声明,则注释后应该有一空行。如: // Traverse the linked list, searching for a match for (Node node = head; node.next != null; node = node.next) { 单行注释可以用于语句之后,中间至少有一空格,模块中的所有单行注释应该左对齐。 5 类类类类 5.1 定义规则定义规则定义规则定义规则 以下是类声明的格式,在方括号内的为可选元素: [ ClassModifiers] class ClassName [ Inheritances] { ClassBody } ClassModifiers(修饰符)是下面关键字的组合: public abstract final Inheritances 是下面数组中的组合: extends SuperClass-父类名 implements Interfaces-接口名,或逗号分开的接口列表(按词汇排序)。 以上的类声明到开括号 “{”为止应在一行,除非超出行限要续行。ClassBody 要缩进四个空 格。闭括号应出现在单独一行的第一列,之后不应有分号。如果类声明有一或多行续行,则应 在开括号后跟一空行。如: // Long class declaration that requires 2 continuation lines. // Notice the opening brace is immediately followed by a blank line. public abstract class VeryLongNameOfTheClassBeingDefined extends VeryLongNameOfTheSuperClassBeingExtended implements Interface1, Interface2, Interface3, Interface4 { static private String buf[256]; } 5.2 类体组织类体组织类体组织类体组织 类体成员应该按照下列顺序组织(每成员之间应排序): Java编程规范 9 1. Static variable field declarations 2. Instance variable field declarations 3. Static initializer 4. Static member inner class declarations 5. Static method declarations 6. Instance initializer 7. Instance constructor declarations 8. Instance member inner class declarations 9. Instance method declarations  成员访问级别 JAVA 类成员按级别从高到低有四种访问级别:public,protected,默认和 private。 类成员应该给予适当的且是最低的级别。如,成员只被同一包的类访问可以设成默认 级别。也就是说定义较低的访问级别能优化编译器,另一方面,定义为 private 级别 则该类被子类扩展带来困难。如某种原因将来该类可能成为子类,而成员可能被子类 访问,则应该定义成 protected。  成员文本注释 所有 public 成员之前应该有一注释行。projected 和默认级别的成员也可以有注释, 这要看程序员的判断力。Private 域不应该有注释,然而,如果函数名称不明显,所 有没注释的域应该用单行注释来描述。  类变量和实例变量域定义 如果有类变量域定义,应放于第一,类变量域有关键字 static 在定义中。如果有实例 变量域则紧跟其后,实例变量在定义中没关键字 static,域定义的格式如下(方括号 内为可选): [FieldModifiers] Type FieldName [= Initializer]; FieldModifiers 是如下合法之组合: public protected private static final transient volatile 域只能单行定义,不能定义在一行成为一组,如: static private int useCount, index; // WRONG static private int useCount; // RIGHT static private long index; // RIGHT  Static initializer 和 static member inner class declarations 格式: static { statements; Java编程规范 10 } public class Outer { static class Inner { //static inner class } }  构造函数定义 构造函数定义中的所有定义元素,直到开括号 “{”为止应该作为一行,除非有续行的发 生。如: /** * Constructs a new empty FooBar. */ public FooBar() { value = new char[0]; } 如有多个构造函数,它们按形参字母顺序排序,且参数少的排在前面。 5.3 方法定义方法定义方法定义方法定义 方法定义中所有定义元素,直到开括号 “{”为止应该作为一行,除非有续行的发生。格式如 下(方括号内可选): [ MethModifiers] Type MethName( Paras) [throws Exceptions]{ MethModifiers 是以下关键字的组合: public protected private abstract static final synchronized native Exceptions 是例外名,或是逗号分开的例外列表,如超过一个应按字母排序。 多于一个方法时应按方法名字母排序,一个例外的情况是:如果类中有 finalize()方法, 则应放于最后。 另外,方法定义如有续行,则在定义的 “{”后,应跟一空行。 例如: // Long method declaration that requires a continuation line. public static final synchronized long methodName() throws ArithmeticException, InterruptedException { static int count; } // Line broken in the middle of a parameter list // Align just after left parenthesis public boolean imageUpdate(Image img, int infoflags, int x, int y, int w, int h) { int i; } Java编程规范 11 5.4 本地内部类和匿名内部类本地内部类和匿名内部类本地内部类和匿名内部类本地内部类和匿名内部类 本地内部类可以定义于方法内,其格式例子如下: Enumeration enumerate() { class Enum implements Enumeration { } return new Enum(); } 匿名内部类一般用于下列情况: 1. 直接用到该类的只有一个地方; 2. 类定义简单,且仅有几行。 匿名类定义规则和命名类相似,但有一些特指的规则:  new 表达式,包括 new 操作符、类型名和开括号应该出现在一行,如果不能满足要求, 应该移 new 表达式到下一行。  匿名类体从 new 表达式开始应该缩进四个空格。  通常闭括号“}”后至少跟一个“;”,“)”或“,”,闭括号的缩进程度与包含 new 表达式的表达式相同,其后没空行。 例如: // Anonymous class inside a return expression Enumeration myEnumerate(final Object array[]) { return new Enumeration() { // new on same line int count = 0; public boolean hasMoreElements() { return count < array.length; } public Object nextElement() { return array[count++]; } }; // } followed by ; } // Anonymous class inside a parenthesized expression helpButton.addActionListener(new ActionListener() { public void actionPerformed(ActionEvent e) { showHelp(); } }); // } followed by ); 5.5 匿名数组表达式和数组初始化匿名数组表达式和数组初始化匿名数组表达式和数组初始化匿名数组表达式和数组初始化 当数组需要赋时就可能用到匿名数组,如果整个匿名数组的初始化能在一行完成,则是可 Java编程规范 12 以接受的。否则,每个数组元素的初始化作为一行。本规则也适用于数组定义时的初始化。 例如: // Example where entire array expression fits on one line Polygon p = new Polygon(new int[] {0, 1, 2}, new int[] {10, 11, 12}, 3); // Example with one array initializer per line String errorMessages[] = { "No such file or directory", "Unable to open file", "Unmatched parentheses in expression" }; // Example of embedded anonymous array expression createMenuItems(new menuItemLabels[] { "Open", "Save", "Save As...", "Quit", }); 5.6 接口接口接口接口 接口和类有相似的风格。接口的定义格式如下,在方括号内的元素是可选的: [public] interface InterfaceName [extends SuperInterfaces] { InterfaceBody } SuperInterfaces 是接口名,或是逗号分开的接口列表,如果接口多于一个则应按接口名字 母排序。接口定义开始于第一列,其定义的所有元素直到 “{”为止,应该位于一行,除非超长需 要续行。接口体缩进四个空格,闭括号单独一行出现,并位于单独一列,结尾没有分号。 接口体的组织顺序: 1. 接口常量域定义 2. 接口方法定义 6 声明声明声明声明 6.1 简单声明简单声明简单声明简单声明  赋值和表达式声明 每行最多一个声明,如: a = b + c; count++; // WRONG Java编程规范 13 a = b + c; // RIGHT count++; // RIGHT  本地变量定义 总的来说,本地变量应该定义在不同的行,然而,不要求初始化的临时变量是例外, 如: int i, j = 4, k; // WRONG int i, k; // acceptable int j = 4; // RIGHT  数组定义 数组的方括号,应紧跟数组名后,在方括号 ‘[“前不能有空格。例外的情况是方法返回 值。如: char[] buf; // WRONG char buf[]; // RIGHT string[] getNames() { // RIGHT, method return value  Return 声明 返回的值不要用括号,除非是复杂的表达式: return(true); // WRONG return true; // RIGHT return (s.length() + s.offset); // RIGHT 6.2 复杂声明复杂声明复杂声明复杂声明 复杂类型要求的风格: 1. 开左括号位于复杂声明开始行的结尾。 2. 闭右括号单独一行,其缩进和声明开始行一致。 3. 大括号 “{。。。}”内部的缩进,按缩进的规则执行。 以下是复杂声明的格式化规则:  if statement: if (condition) { statements; } if (condition) { statements; } else { statements; } Java编程规范 14 if (condition) { statements; } else if ( condition) { statements; } else { statements; }  for statement: for (initialization; condition; update) { statements; }  while statement: while ( condition) { statements; }  对于无限循环不用 “for (;;) { ... } ”而用如下格式: while (true) { statements; }  do-while statement: do { statements; } while ( condition);  synchronized statement: synchronized ( expression) { statements; }  try statement: try { statements; } catch ( exception-declaration) { statements; } try { statements; } finally { statements; } Java编程规范 15 try { statements; } catch ( exception-declaration) { statements; } finally { statements; } Appendix A Appendix A Appendix A Appendix A ---- Java Coding Style ExampleJava Coding Style ExampleJava Coding Style ExampleJava Coding Style Example /* * @(#)CodingStyleExample.java 1.0 98/01/23 Achut Reddy * * Copyright (c) 1994-1998 Sun Microsystems, Inc. All Rights Reserved. */ package com.sun.examples; import java.applet.Applet; import java.awt.Point; /** * A class to demonstrate good coding style. */ public class CodingStyleExample extends Applet implements Runnable { static final int BUFFER_SIZE = 4096; // default buffer size StringBuffer name; // my name Point starshipCoordinates[]; // ship locations /** * Compute the total distance between a set of Points. * @param starshipCoordinates the locations of all known starships * @param numberOfPoints the number of points in the array * @return the total distance */ public int computeDistances(Point starshipCoordinates[], int numberOfPoints) throws Exception { int distance = 0; // accumulates distances // Compute distance to each starship and add it to the total for (int i = 0; i < numberOfPoints; i++) { distance += Math.sqrt((double)((starshipCoordinates[i].x * starshipCoordinates[i].x) + (starshipCoordinates[i].y * starshipCoordinates[i].y))); } if (distance > 100000) { throw new Exception(); } return distance; } /** * Called whenever Thread.start() is called for this class */ Java编程规范 16 public void run() { try { name.append("X"); System.out.println(name); } catch (Exception e) { name = new StringBuffer(BUFFER_SIZE); } } }
还剩18页未读

继续阅读

下载pdf到电脑,查找使用更方便

pdf的实际排版效果,会与网站的显示效果略有不同!!

需要 6 金币 [ 分享pdf获得金币 ] 0 人已下载

下载pdf

pdf贡献者

jangoooo

贡献于2015-07-10

下载需要 6 金币 [金币充值 ]
亲,您也可以通过 分享原创pdf 来获得金币奖励!
下载pdf