java 编程规范[Oreilly_Java_Cookbook].pdf

JAVA编程指南编程指南 版本版本 修订历史记录修订历史记录 日期日期 版本版本 说明说明 作者作者 2001-9-20 1.0 编写 L.j 页码，1/82002-3-18http:/ 1.简介 1.1 目的 1.2 范围 1.3 定义、首字母缩写词和缩略语 1.4 引用 1.5 概述 2.代码组织与风格 2.1 Tab 2.2 缩进 2.3 空行 2.4 代码块长度 2.5 “”，“”2.6 行宽 2.7 空格 3.注释 3.1 注释的基本约定 3.2 注释类型 3.3 注释哪些部分 4.命名 5.声明 6.表达式和语句 7.内存管理 8.错误处理和异常事件 9.可移植性 10.复用 11.编译问题 12.附录：指南概要 页码，2/82002-3-18http:/ 1.简介简介 1.1 目的目的 本规范为一套编写高效可靠的 Java 代码的标准、约定和指南。它以安全可靠的软件工程原则为基础，使代码易于理解、维护和增强，提高生产效率。同时，将带来更大的一致性，使软件开发团队的效率明显提高。1.2 范围范围 本规范应用于采用J2EE规范的项目中，所有项目中的JAVA代码（含JSP,SERVLET,JAVABEAN）均应遵守这个规范。同时，也可作为其它项目的参考。1.3 引用引用 Code Conventions for the Java Programming Language.How to Write Doc Comments for Javadoc 2.代码组织与风格代码组织与风格 2.1 Tab 一个Tab为4个空格长。2.2 缩进缩进 一个代码块内的代码都应该统一的缩进一个Tab长度。2.3 空行空行 适当的增加空行，来增加代码的可读性。在下列情况下应该有两行空行：?同一文件的不同部分之间；?在类，接口以及彼此之间；在下列情况之间应该有一行空行：?方法之间；?局部变量和它后边的语句之间；?方法内的功能逻辑部分之间；2.4 代码块长度代码块长度 每个代码块尽量控制在1个屏幕之内，方便浏览。2.5“”，“”，“”开括号“”放在块的所有者所在行的最后面，闭括号“”单独放在代码块的最后一行。2.6 行宽行宽 每行代码和注释不应超过70个字节或屏幕的宽度，如超过则应换行，换行后的代码应该缩进8个字符。2.7 空格空格 括号和它里面的字符之间不应该出现空格。括号应该和它前边的关键词留有空格，如：while(true);但是方法名和左括号之间不应该有空格。参数之间的逗号后应该加一空格。如：method1(int i1,int i2)for语句里的表达式之间加一空格。如：for(expr1;expr2;expr3)二元操作符和操作数之间应该用空格隔开。如：i+c;强制类型转换时，在类型和变量之间加一空格。如：(int)i;3.注释注释 页码，3/82002-3-18http:/ 注释的基本约定注释的基本约定 3.1.1 注释应该增加代码的清晰度 3.1.2 持注释的简洁，不是任何代码都需要注释的，过多的注释反而会影响代码的可读性。3.1.3 注释不应该包括其他的特殊字符。3.1.4 先写注释，后写代码 3.2 注释类型注释类型 3.2.1 块注释：主要用来描述文件，类，方法，算法等。一般用在文档和方法的前面，也可以放在文档的任何地方。以/*开头，*/结尾。例：/*注释*/3.2.2 行注释：主要用在方法内部，对代码，变量，流程等进行说明。与块注释格式相似，但是整个注释占据一行。例：/*注释*/3.2.3 尾随注释：与行注释功能相似，放在代码的同行，但是要与代码之间有足够的空间，便于分清。例：int m=4;/*注释*/如果一个程序块内有多个尾随注释，每个注释的缩进应该保持一致。3.2.4 行尾注释：与行注释功能相似，放在每行的最后，或者占据一行。以/开头。3.2.5 文档注释：与块注释相似，但是可以被javadoc处理，生成HTML文件。以/*开头，*/结尾。问挡住是不能放在方法或程序块内。例：/*注释*/3.3 注释那些部分注释那些部分 项目项目 注释哪些部分注释哪些部分 实参/参数 参数类型 参数用来做什么 任何约束或前提条件 示例 字段/字段/属性 字段描述 注释所有使用的不变量 示例 并行事件 可见性决策 类 类的目的 已知的问题 类的开发/维护历史 注释出采用的不变量 并行策略 编译单元 每一个类/类内定义的接口，含简单的说明 页码，4/82002-3-18http:/ 4.命名命名 4.1 命名的基本约定命名的基本约定 4.1.1 一般应该使用可以准确说明变量/字段/类的完整的英文描述符，如firstName。对一些作用显而易见的变量可以采用简单的命名，如在循环里的递增（减）变量就可以被命名为”i”。4.1.2 尽量采用项目所涉及领域的术语。4.1.3 可以采用大小写混合，提高名字的可读性。4.1.4 尽量少用缩写，但如果一定要使用，就要谨慎地使用。同时，应该保留一个标准缩写的列表，并且在使用时保持一致。4.1.5 避免使用长名字（最好不超过 15 个字母）。4.1.6 避免使用相似或者仅在大小写上有区别的名字。4.1.7 避免使用下划线作为名字的首末字母。4.2 标示符的命名约定标示符的命名约定 文件名和/或标识信息 版权信息 接口 目的 它应如何被使用以及如何不被使用 局部变量 用处/目的 成员函数注释 成员函数做什么以及它为什么做这个 哪些参数必须传递给一个成员函数 成员函数返回什么 已知的问题 任何由某个成员函数抛出的异常 可见性决策 成员函数是如何改变对象的 包含任何修改代码的历史 如何在适当情况下调用成员函数的例子适用的前提条件和 后置条件 成员函数内部注释 控制结构 代码做了些什么以及为什么这样做 局部变量 难或复杂的代码 处理顺序 标 示符 类型 命名约定 例子 包?全部小写。?标识符用点号分隔开来。为了使包的名字更局部包：interface.screens 全局包：页码，5/82002-3-18http:/ 公司建议包名中的标识符用点号来分隔。?Sun 公司的标准 java 分配包用标识符.java 开头。?全局包的名字用你的机构的 Internet 保留域名开头。com.rational.www.interface.screens 类，接口?类的名字应该使用名词。?每个单词第一个字母应该答谢。?比面使用单词的错写，除非它的缩写已经广为人知，如HTTP。Class Hello;Class HelloWorld;Interface Apple;方法?第一个单词一般是动词。?第一个字母是小些，但是中间单词的第一个字母是大写。?如果方法返回一个成员变量的值，方法名一般为get+成员变量名，如若返回的值是bool变量，一般以is作为前缀。?如果方法修改一个成员变量的值，方法名一般为：set+成员变量名。getName();setName();isFirst();变量?第一个字母小写，中间单词的第一个字母大写。?不要用_或&作为第一个字母。?尽量使用短而且具有意义的单词。?单字符的变量名一般只用于生命期非常短暂的变量。i,j,k,m,n一般用于integers；c,d,e一般用于characters。?如果变量是集合，则变量名应用复数。?命名组件采用匈牙利命名法，所有前缀均应遵循同一个组件名称缩写String myName;int i;int n;char c;int students;btNew;(bt是Button的缩写)页码，6/82002-3-18http:/ 5.声明声明 5.1 每行应该只有一个声明。每行应该只有一个声明。5.2 局部变量必须初始化。局部变量必须初始化。5.3 除了除了for循环外，声明应该放在块的最开始部分。循环外，声明应该放在块的最开始部分。for循环中的变量声明可以放在循环中的变量声明可以放在for语句中。如：语句中。如：for(int i=0;i10;i+)。5.4 避免块内部的变量与它外部的变量名相同。避免块内部的变量与它外部的变量名相同。5.5 6.表达式和语句表达式和语句 6.1 每行应该只有一条语句。每行应该只有一条语句。6.2 if-else,if-elseif语句，任何情况下，都应该有“语句，任何情况下，都应该有“”，“”，“”，格式如下：”，格式如下：if(condition)statements;else if(condition)statements;else statements;6.3 for语句格式如下：语句格式如下：for(initialization;condition;update)statements;如果语句为空：for(initialization;condition;update);6.4 while语句格式如下：语句格式如下：while(condition)statements;如果语句为空:while(condition);6.56.5 do-while语句格式如下：do-while语句格式如下：do statements;while(condition);6.66.6 switch语句，每个switch里都应包含default子语句,格式如下：switch语句，每个switch里都应包含default子语句,格式如下：switch(condition)case ABC:statements;/*falls through*/case DEF:statements;列表。常量?所有常量名均全部大写，单词间以_隔开。int MAX_NUM;页码，7/82002-3-18http:/ break;case XYZ:statements;break;default:statements;break;6.76.7 try-catch语句格式如下：try-catch语句格式如下：try statements;catch(ExceptionClass e)statements;finally statements;7.错误处理和异常事件错误处理和异常事件 通常的思想是只对错误采用异常处理：逻辑和编程错误，设置错误，被破坏的数据，资源耗尽，等等。通常的法则是系统在正常状态下以及无重载和硬件失效状态下，不应产生任何异常。异常处理时可以采用适当的日志机制来报告异常，包括异常发生的时刻。不要使用异常实现来控制程序流程结构。8.可移植性可移植性 8.1 尽量不要使用已经被标为不赞成使用的类或方法。尽量不要使用已经被标为不赞成使用的类或方法。8.28.2 代码应遵循代码应遵循UNIX风格。风格。8.38.3 如果需要换行的话，尽量用 println 来代替在字符串中使用 n。如果需要换行的话，尽量用 println 来代替在字符串中使用 n。8.4 用用separator()方法代替路径中的方法代替路径中的”/”或或”。8.5 用用pathSeptarator()方法代替路径中的 方法代替路径中的”:”或 或”;”。页码，8/82002-3-18http:/