1、Java 编 码 规 范_编码规范_Java 编 码 规 范修订历史记录文档标识 LENOVO-JAVA-1_0.doc 页数文档名称 JAVA 编码规范序号 修改描述 版本号 日期 作者1 创建文档 1.0 2010/04/01 胡少华Java 编 码 规 范1. 应用范围 .32. 设计类和方法 .32.1 创建具有很强内聚力的类 .32.2 创建松散连接和高度专用的方法 .32.3 编程原则 .43. 命名约定 .53.1 包、类及方法命名 .53.2 其它 .64. 使用常量 .64.1 使用常量 .65. 变量 .75.1 定义有焦点的变量 .75.2 只对常用变量名和长变量名进行缩
2、写 .75.3 使用统一的量词 .75.4 使用肯定形式的布尔变量 .75.5 为每个变量选择最佳的数据类型 .75.6 尽量缩小变量的作用域 .86. 代码的格式化 .86.1 对代码进行格式化时，要达到的目的 .86.2 编程原则 .87. 代码的注释 .97.1 使用代码注释的目的 .97.2 编程原则 .97.3 注释哪些部分 .117.4 示例 .117.4.1 块注释： 117.4.2 行注释： 127.4.3 尾随注释： 127.4.4 行尾注释： 127.4.5 文档注释： 12Java 编 码 规 范8. 表达式和语句 .128.1 每行应该只有一条语句。 .128.2 if
3、-else,if-elseif 语句，任何情况下，都应该有“ ”，“”，格式如下： .128.3 for 语句格式如下： 138.4 while 语句格式如下： 138.5 do-while 语句格式如下： 138.6 switch 语句，每个 switch 里都应包含 default 子语句,格式如下： 138.7 try-catch 语句格式如下： 139. 错误处理和异常事件 .1410. 封装、事务 .1411. 可移植性 .14Java 编 码 规 范1. 应用范围本规范应用于采用 J2EE 规范的项目中，所有项目中的 JAVA 代码（含JSP， SERVLET，JAVABEAN，E
4、JB）均应遵守这个规范。2. 设计类和方法2.1 创建具有很强内聚力的类方法的重要性往往比类的重要性更容易理解，方法是指执行一个统一函数的一段代码。类常被错误的视为是一个仅仅用于存放方法的容器。有些开发人员甚至把这种思路作了进一步的发挥，将他们的所有方法放入单个类之中。之所以不能正确的认识类的功能，原因之一是类的实现实际上并不影响程序的执行。当一个工程被编译时，如果所有方法都放在单个类中或者放在几十个类中，这没有任何关系。虽然类的数量对代码的执行并无太大的影响，但是当创建便于调试和维护的代码时，类的数量有时会带来很大的影响。类应该用来将相关的方法组织在一起。当类包含一组紧密关联的方法时，该类可
5、以说具有强大的内聚力。当类包含许多互不相关的方法时，该类便具有较弱的内聚力。应该努力创建内聚力比较强的类。大多数工程都包含许多并不十分适合与其他方法组合在一起的方法。在这种情况下，可以为这些不合群的方法创建一个综合性收容类。创建类时，应知道“模块化”这个术语的含义是什么。类的基本目的是创建相当独立的程序单元。2.2 创建松散连接和高度专用的方法1. 使所有方法都执行专门的任务 每个方法都应执行一项特定的任务，它应出色的完成这项任务。应避免创建执行许多不同任务的方法。创建专用方法有许多好处。首先调试将变得更加容易。2. 尽量使方法成为自成一体的独立方法 当一个方法依赖于其他方法的调用时，称为与其
6、他方法紧密连接的方法。紧密连接的方法会使调试和修改变得比较困难，因为它牵涉到更多的因素。松散连接的方法优于紧密连接的方法，但你不可能使每个方法都成为独立的方法。若要使方法具备较强的独立性，方法之一是尽量减少类变量。创建方法时，设法将每个方法视为一个黑箱，其他例程不应要求了解该方法的内部工作情况，该方法也不应要求了解它外面的工程情况。这就是为什么你的方法应依靠参数而不应依靠全局变量的原因。创建专用方法时，请考虑下列指导原则：1） 将复杂进程放入专用方法。如果应用程序使用复杂的数学公式，请考虑将每个公式放入它自己的方法中。这样使用这些公式的其他方法就不包含用于该公式的实际代码。这样也可以更容易发现
7、与公式相关的问题。 Java 编 码 规 范2） 将数据输入/输出（I/O）放入专用方法。 3） 将专用方法中可能要修改的代码隔离。如果你知道某个进程经常变更，请将这个多变的代码放入专用方法，以便以后可以更容易的进行修改，并减少无意中给其他进程带来问题的可能性。 4） 将业务规则封装在专用方法中。业务规则常属于要修改的代码类别，应与应用程序的其余部分隔开。其他方法不应知道业务规则，只有要调用的方法才使用这些规则。 3. 设计类和方法时，要达到下列目的： 1） 创建更加容易调试和维护的方法2） 创建具有强大内聚力的类3） 创建高度专用的方法4） 创建松散连接的方法5） 尽量使方法具有独立性6）
8、提高方法的扇入性7） 降低方法的扇出性2.3 编程原则1. 为方法和类赋予表义性强的名字 为了使代码更加容易理解，最容易的方法之一是为你的方法赋予表义性强的名字。函数名DoIt、GetIt 的可读性很难与 CalculateSalesTax、 RetrieveUserID 相比。由缩写方法名组成的代码很难理解和维护，没有理由再这样做了。给方法正确的命名，可使程序工程的调试和维护工作大大的改观。请认真对待方法命名的工作，不要为了减少键入操作量而降低方法的可理解度。实际应用举例：1） 给方法命名时应大小写字母混合使用。如果句子全使用大写字母，那么阅读起来就非常困难，而大小写字母混合使用的句子，阅读
9、起来就很容易。 2） 定义方法名时不要使用缩写。如果你认为应用程序中的某些工程应使用缩写，那么请将这些情况加上注释，并确保每个人在所有时间内都使用这些缩写。决不要在某些方法中对某些单词进行缩写，而在别的方法中却不使用缩写。 2. 为每个方法赋予单个退出点3. 创建方法时，始终都应显式地定义它的作用域。 1） 如果你真的想创建一个公用方法，请向代码阅读者说明这一点。2） 通过为每个方法赋予一个明确定义的作用域，可以减少代码阅读者需要投入的工作量。应确保你为方法赋予最有意义的作用域。如果一个方法只被同一类中的另一个方法调用，那么请将它创建成私有方法。如果该方法是从多个类中的多个方法中调用，请将该说
10、明为公用方法。Java 编 码 规 范4. 用参数在方法之间传递数据应尽量避免使用类变量。一般来说，变量的作用域越小越好。为了减少类变量，方法之一是将数据作为参数在不同方法之间传递，而不是让方法共享类变量。1） 为每个参数指定数据类型。 2） 始终要对数进行检验，决不要假设你得数据没有问题。程序员常犯的一个错误是在编写方法时假设数据没有问题。在初始编程阶段，当编写调用方法时，这样的假设并无大碍。这时你完全能够知道什么是参数的许可值，并按要求提供这些值。但如果你不对参数的数据进行检验，那么下列情况就会给你带来很大麻烦：另外某个人创建了一个调用方法，但此人不知道允许的值；你在晚些时候添加了新的调用
11、方法，并错误的传递了坏数据。3. 命名约定所有变量的定义应该遵循匈牙利命名法，它使用 3 字符前缀来表示数据类型，3 个字符的前缀必须小写，前缀后面是由表意性强的一个单词或多个单词组成的名字，而且每个单词的首写字母大写，其它字母小写，这样保证了对变量名能够进行正确的断句。这样，在一个变量名就可以反映出变量类型和变量所存储的值的意义两方面内容，这使得代码语句可读性强、更加容易理解。3.1 包、类及方法命名标示符类型 命名约定 例子包 全部小写。 标识符用点号分隔开来。为了使包的名字更易读，Sun 公司建议包名中的标识符用点号来分隔。 Sun 公司的标准 java 分配包用标识符 .java 开头
12、。 全局包的名字用你的机构的 Internet 保留域名开头 。局部包：interface.screens全局包：com.rational.www. interface.screens类，接口 类的名字应该使用名词。 每个单词第一个字母应该大写。 避免使用单词的缩写，除非它的缩写已经广为人知，如 HTTP。Class Hello ;Class HelloWorld ;Interface Apple ;方法 第一个单词一般是动词。 第一个字母是小些，但是中间单词的第一个字母是大写。 如果方法返回一个成员变量的值，方法名一般为get+成员变量名，如若返回的值是 bool 变量，一般以 is 作为前
13、缀。 如果方法修改一个成员变量的值，方法名一般为：set + 成员变量名。getName();setName();isFirst();Java 编 码 规 范变量 第一个字母小写，中间单词的第一个字母大写。 不要用_或int students;int i;int n;char c;btNew;(bt 是 Button 的缩写)常量 所有常量名均全部大写，单词间以_隔开。 int MAX_NUM;3.2 其它开发人员如果遇到上述表格中未列举的类型，请书面通知相关管理人员，由管理人员集中更新列表内容，不得擅自启用未经确定的新变量前缀。4. 使用常量4.1 使用常量1. 常数很容易在数据输入时出错
14、常数存在的主要问题之一是你很容易在键入数字时出错，从而颠倒了数字的位置。例如，当你键入数字 10876 时，很容易的键入 10867 或 18076。与处理变量和保留字的方法不同，编译器并不在乎颠倒了位置和不正确的数字，有时简单的错误造成的问题不会立即表现出来，而当问题表现出来时，它们会以随机的计算错误的形式出现，这些错误很难准确定位。用常量来取代常数时，编译器将在编译时检查常量的有效性。如果常量不存在，编译器便将这一情况通知你，并拒绝进行编译，这可以消除错误键入的数字带来的问题，只要常量拥有正确的值，使用该常量的所有代码也有使用该正确值。2. 常数很难不断更新3. 常量使代码更容易阅读使用常
15、量后，得到的一个额外好处是可使创建的代码更容易阅读。常数很不直观。也许你对常数非常了解，但其他人则根本看不明白。通过合理的给常量命名，使用这些常量的代码就变得比较直观了，更容易阅读。为常量赋予较宽的作用域，这与使用变量时的情况不同。在一个应用程序中你决不应该两次创建相同的常量。如果你发现自己复制了一个常量，请将原始的常量说明转至较宽的作用域，直到该常量可供引用它的所有方法为止。4. 常量的用法Java 中常量的声明方式：static final int QUERY_PAGE_SIZE=10;在 Java 编译阶段，代码中引用的常量将被替换成为具体的值，考虑到公司生产维护的方式，项目中避免跨类使
16、用 static final 常量，如果需要跨类使用，可考虑使用静态变量，Java 编 码 规 范如：static int QUERY_PAGE_SIZE=10;5. 变量5.1 定义有焦点的变量用于多个目的的变量称为无焦点（多焦点）的变量。无焦点变量所代表的意义与程序的执行流程有关，当程序处于不同位置时，它所表示的意义是不固定的，这样就给程序的可读性和可维护性带来了麻烦。5.2 只对常用变量名和长变量名进行缩写如果需要对变量名进行缩写时，一定要注意整个代码中缩写规则的一致性。例如，如果在代码的某些区域中使用 Cnt，而在另一些区域中又使用 Count，就会给代码增加不必要的复杂性。变量名中尽
17、量不要出现缩写。5.3 使用统一的量词通过在结尾处放置一个量词，就可创建更加统一的变量，它们更容易理解，也更容易搜索。例如，请使用 strCustomerFirst 和 strCustomerLast，而不要使用 strFirstCustomer 和strLastCustomer。量词列表：量词后缀 说明First 一组变量中的第一个Last 一组变量中的最后一个Next 一组变量中的下一个变量Prev 一组变量中的上一个Cur 一组变量中的当前变量5.4 使用肯定形式的布尔变量给布尔变量命名时，始终都要使用变量的肯定形式，以减少其它开发人员在理解布尔变量所代表的意义时的难度。5.5 为每个变
18、量选择最佳的数据类型这样即能减少对内存的需求量，加快代码的执行速度，又会降低出错的可能性。用于Java 编 码 规 范变量的数据类型可能会影响该变量进行计算所产生的结果。在这种情况下，编译器不会产生运行期错误，它只是迫使该值符合数据类型的要求。这类问题极难查找。5.6 尽量缩小变量的作用域如果变量的作用域大于它应有的范围，变量可继续存在，并且在不再需要该变量后的很长时间内仍然占用资源。它们的主要问题是，任何类中的任何方法都能对它们进行修改，并且很难跟踪究竟是何处进行修改的。占用资源是作用域涉及的一个重要问题。对变量来说，尽量缩小作用域将会对应用程序的可靠性产生巨大的影响。6. 代码的格式化6.
19、1 对代码进行格式化时，要达到的目的1. 通过代码分割成功能块和便于理解的代码段，使代码更容易阅读和理解；2. 使用空行和注释行，将程序中逻辑上不相关的代码块分开。比如：变量声明部分和代码语句间的分隔；较长的方法中，完成不同功能的代码块间的分隔。要避免出现逻辑上混乱的分隔，如：某一逻辑功能代码块中间用空行进行了分隔，但是在相邻功能代码块之间却没有分隔，这样会给程序阅读者造成错觉。3. 减少为理解代码结构而需要做的工作；4. 使代码的阅读者不必进行假设；5. 使代码结构尽可能做到格式清楚明了。6.2 编程原则1. 不要将多个语句放在同一行上 不论是变量声明，还是语句都不要在一行上书写多个。2.
20、缩进后续行 当你将变量设置为某个值时，所有后续行的缩进位置应与第一行的变量值相同；当你调用一个方法时，后续行缩进到第一个参数的开始处；当你将变量或属性设置为等于表达式的计算结果时，请从后面分割该语句，以确保该表达式尽可能放在同一行上。3. 在 if 语句后缩进； 在 else 语句后缩进Java 编 码 规 范在 switch 语句后缩进在 case 语句后缩进在 do 句后缩进已经用行接续符分割的语句的各个行要缩进对从属于行标注的代码进行缩进。4. 在执行统一任务的各个语句组之间插入一个空行。好的代码应由按逻辑顺序排列的进程或相关语句组构成。 7. 代码的注释7.1 使用代码注释的目的1.
21、文字说明代码的作用( 即为什么要用编写该代码 ,而不是如何编写 ); 2. 确指出该代码的编写思路和逻辑方法; 3. 人们注意到代码中的重要转折点; 4. 使代码的阅读者不必在他们的头脑中仿真运行代码的执行方法.7.2 编程原则1. 用文字说明代码的作用:简单的重复代码做写什么,这样的注释几乎不能给注释增加什么信息.如果你使用好的命名方法来创建直观明了的代码那么这些类型的注释绝对增加不了什么信息.2. 如果你想违背好的编程原则,请说明为什么有的时候你可能需要违背好的编程原则，或者使用了某些不正规的方法，.遇到这种情况时,请用内部注释来说明你在做什么和为什么要这样做。技巧性特别高的代码段，一定要
22、加详细的注释，不要让其他开发人员花很长时间来研究一个高技巧但不易理解的程序段。3. 用注释来说明何时可能出错和为什么出错4. 在编写代码前进行注释给代码加注释的方法之一是在编写一个方法前首先写上注释.如果你愿意,可以编写完整句子的注释或伪代码.一旦你用注释对代码进行了概述,就可以在注释之间编写代码.5. 在要注释的代码前书写注释注释一定出现在要注释的程序段前，不要在某段程序后书写对这段程序的注释，先看到注释对程序的理解会有一定帮助。Java 编 码 规 范如果有可能，请在注释行与上面代码间加一空行。6. 纯色字符注释行只用于主要注释注释中要分隔时，请使用一行空注释行来完成，不要使用纯色字符，以
23、保持版面的整洁、清晰。7. 避免形成注释框用星号围成的注释框，右边的星号看起来很好,但它们给注释增加了任何信息吗?实际上这会给编写或编辑注释的人增加许多工作。8. 增强注释的可读性注释是供人阅读的，而不是让计算机阅读的。1） 使用完整的语句。虽然不必将注释分成段落（最好也不要分成段落），但你应尽量将注释写成完整的句子。 2） 避免使用缩写。缩写常使注释更难阅读，人们常用不同的方法对相同的单词进行缩写，这会造成许多混乱，如果必须对词汇缩写，必须做到统一。 3） 将整个单词大写，以突出它们的重要性。若要使人们注意注释中的一个或多个单词，请全部使用大写字母。 9. 对注释进行缩进，使之与后随的语句对
24、齐。注释通常位于它们要说明的代码的前面。为了从视觉上突出注释与它的代码之间的关系，请将注释缩进，使之与代码处于同一个层次上。10. 为每个方法赋予一个注释标头每个方法都应有一个注释标头。方法的注释标头可包含多个文字项，比如输入参数、返回值、原始作者、最后编辑该方法的程序员、上次修改日期、版权信息。11. 当行尾注释用在上面这种代码段结构中时，它们会使代码更难阅读。使用多个行尾注释时（比如用于方法顶部的多个变量说明），应使它们互相对齐。这可使它们稍容易阅读一些。12. 何时书写注释1） 请在每个 if 语句的前面加上注释。 2） 在每个 switch 语句的前面加上注释。与 if 语句一样，sw
25、itch 语句用于评估对程序执行产生影响的表达式。 3） 在每个循环的前面加上注释。每个循环都有它的作用，许多情况下这个作用不清楚直观。 7.3 注释哪些部分Java 编 码 规 范项目 注释哪些部分实参/ 参数参数类型 参数用来做什么任何约束或前提条件示例字段/ 字段/属性字段描述 注释所有使用的不变量示例并行事件可见性决策类 类的目的 已知的问题类的开发/维护历史注释出采用的不变量并行策略编译单元 每一个类/类内定义的接口，含简单的说明 文件名和/或标识信息版权信息接口 目的 它应如何被使用以及如何不被使用局部变量 用处/目的成员函数注释 成员函数做什么以及它为什么做这个 哪些参数必须传递
26、给一个成员函数成员函数返回什么已知的问题任何由某个成员函数抛出的异常可见性决策成员函数是如何改变对象的包含任何修改代码的历史如何在适当情况下调用成员函数的例子适用的前提条件和后置条件成员函数内部注释 控制结构 代码做了些什么以及为什么这样做局部变量难或复杂的代码处理顺序7.4 示例7.4.1 块注释：主要用来描述文件，类，方法，算法等。一般用在文档和方法的前面，也可以放在文档的任何地方。以/*开头， */结尾。例：/*Java 编 码 规 范* 注释*/7.4.2 行注释：主要用在方法内部，对代码，变量，流程等进行说明。与块注释格式相似，但是整个注释占据一行。例：/* 注释 */7.4.3 尾
27、随注释：与行注释功能相似，放在代码的同行，但是要与代码之间有足够的空间，便于分清。例：int m=4 ; /* 注释 */如果一个程序块内有多个尾随注释，每个注释的缩进应该保持一致。7.4.4 行尾注释：与行注释功能相似，放在每行的最后，或者占据一行。以/开头。7.4.5 文档注释：与块注释相似，但是可以被 javadoc 处理，生成 HTML 文件。以 /*开头，*/结尾。文档注释不能放在方法或程序块内。例：/*注释*/8. 表达式和语句8.1 每行应该只有一条语句。8.2 if-else,if-elseif 语句，任何情况下，都应该有“”，“”，格式如下：if (condition) st
28、atements; else if (condition) statements; elsestatements;Java 编 码 规 范8.3 for 语句格式如下：for (initialization; condition; update) statements;如果语句为空：for (initialization; condition; update) ;8.4 while 语句格式如下：while (condition) statements;如果语句为空:while (condition);8.5 do-while 语句格式如下：do statements; while (cond
29、ition);8.6 switch 语句，每个 switch 里都应包含 default 子语句,格式如下：switch (condition) case ABC:statements;/* falls through */case DEF:statements;break;case XYZ:statements;break;default:statements;break;8.7 try-catch 语句格式如下：try statements; catch (ExceptionClass e) statements; finally statements;Java 编 码 规 范9. 错误处
30、理和异常事件通常的思想是只对错误采用异常处理：逻辑和编程错误，设置错误，被破坏的数据，资源耗尽，等等。通常的法则是系统在正常状态下以及无重载和硬件失效状态下，不应产生任何异常。异常处理时可以采用适当的日志机制来报告异常，包括异常发生的时刻。不要使用异常实现来控制程序流程结构。10. 封装、事务1. 非商务公用组件单独封装2. 每一个业务流程单独封装3. 一次方法（组件）的调用应能完成某一项功能或流程，即符合完整性4. 一次方法（组件）的调用符合 ACID 事务性5. 多次方法（组件）的调用应包含在一个事务中11. 可移植性1. 尽量不要使用已经被标为不赞成使用的类或方法。2. 如果需要换行的话
31、，尽量用 println 来代替在字符串中使用“n“。 3. 用 separator()方法代替路径中的”/”或” 。4. 用 pathSeptarator()方法代替路径中的 ” : ” 或 ” ;” 。12. 性能与安全 12.1 基本原则 性能的提升并不是一蹴而就的，而是由良好的编程积累的，虽然任何良好的习惯和经验所提升的性能都十分有限，甚至微乎其微，但良好的系统性能却是由这些习惯等积累而成，不积细流，无以成江海！ 12.2 String 与 StringBugffer 不要使用如下 String 初始化方法： String str = new String(“abcdef”); 这将产
32、生两个对象，应当直接赋值： String str = “abcdef”; 在处理可变 String 的时候要尽量使用 StringBuffer 类， StringBuffer 类是构成 String 类的基础。String 类将 StringBuffer 类封装了起来，（以花费更多时间为代价）为开发人员提供了一个安全的接口。当我们在构造字符串的时候，我们应该用 StringBuffer 来实现Java 编 码 规 范大部分的工作，当工作完成后将 StringBuffer 对象再转换为需要的 String 对象。比如：如果有一个字符串必须不断地在其后添加许多字符来完成构造，那么我们应该使用 St
33、ringBuffer 对象和她的 append() 方法。如果我们用 String 对象代替 StringBuffer 对象的话，将会花费许多不必要的创建和释放对象的 CPU 时间。 12.3 集合 避免使用 Vector 和 HashTable 等旧的集合实现，这些实现的存在仅是为了与旧的系统兼容，而且由于这些实现是同步的，故而在大量操作时会带来不必要的性能损失。在新的系统设计中不当出现这些实现，使用 ArrayList 代替 Vector，使用 HashMap 代替HashTable。 若却是需要使用同步集合类，当使用如下方式获得同步集合实例： Map map = Collections.
34、synchronizedMap(new HashMap(); 由于数组、ArrayList 与 Vector 之间的性能差异巨大（具体参见Java fitball），故在能使用数组时不要使用 ArrayList，尽量避免使用 Vector。 12.4 对象 避免在循环中频繁构建和释放对象。 不再使用的对象应及时销毁。 如无必要，不要序列化对象。 12.5 同步 在不需要同步操作时避免使用同步操作类，如能使用 ArrayList 时不要使用 Vector。 尽量少用同步方法，避免使用太多的 synchronized 关键字。 尽量将同步最小化，即将同步作用到最需要的地方，避免大块的同步块或方法等
35、。 12.6 final 将参数或方法声明成 final 可提高程序响应效率，故此： 注意绝对不要仅因为性能而将类、方法等声明成 final，声明成 final 的类、方法一定要确信不再被继承或重载！ 不需要重新赋值的变量（包括类变量、实例变量、局部变量）声明成 final 所有方法参数声明成 final 私有(private)方法不需要声明成 final 若方法确定不会被继承，则声明成 final 12.7 垃圾收集和资源释放 不要过分依赖 JVM 的垃圾收集机制，因为你无法预测和知道 JVM 在什么时候运行GC。 尽可能早的释放资源，不再使用的资源请立即释放。 可能有异常的操作时必须在 try 的 finally 块中释放资源，如数据库连接、IO 操作等： Java 编 码 规 范Connection conn = null; try /do something catch(Exception e) /异常捕捉和处理 e.printStackTrack(); finally /判断 conn 等是否为 null if(null != conn) conn.close(); /end try.catch.finally
