项目代码编程规范

1、项目代码编程规范1. 应用范围本规范应用于采用 J2EE规范的项目中，所有项目中的JAVA代码(含JSP, SERVLET JAVABEAN EJB) JS代码、HTML弋码及数据库设计均应遵守这个规范。同时，也可作为其它项目的参考。2. 设计类和方法2.1. 创建具有很强内聚力的类方法的重要性往往比类的重要性更容易理解，方法是指执行一个独立逻辑的一段代码。类常被错误的视为是一个仅仅用于存放方法的容器。有些开发人员甚至把这种思路作了进一步的发挥，将他们的所有方法放入单个类之中。之所以不能正确的认识类的功能，原因之一是类的实现实际上并不影响程序的执行。当一个工程被编译时，如果所有方法都放在单个类

2、中或者放在几十个类中，这没有任何关系。虽然类的数量对代码的执行并无太大的影响，但是当创建便于调试和维护的代码时，类的数量有时会带来很大的影响。类应该用来将相关的方法组织在一起。当类包含一组紧密关联的方法时，该类可以说具有强大的内聚力。当类包含许多互不相关的方法时，该类便具有较弱的内聚力。应该努力创建内聚力比较强的类。大多数工程都包含许多并不十分适合与其他方法组合在一起的方法。在这种情况下，可以为这些不合群的方法创建一个综合性收容类。创建类时，应知道“模块化”这个术语的含义是什么。类的基本目的是创建相当独立的程 序单元。2.2. 创建松散连接和高度专用的方法2.2.1. 使所有方法都执行专门的任

3、务每个方法都应执行一项特定的任务，它应出色的完成这项任务。应避免创建执行许多不同 任务的方法。创建专用方法有许多好处。首先调试将变得更加容易。2.2.2. 尽量使方法成为自成一体的独立方法当一个方法依赖于其他方法的调用时，称为与其他方法紧密连接的方法。紧密连接的方法会使调试和修改变得比较困难，因为它牵涉到更多的因素。松散连接的方法优于紧密连接的方法，但你不可能使每个方法都成为独立的方法。若要使方法具备较强的独立性，方法之一是尽量减少类变量。创建方法时，设法将每个方法视为一个黑箱，其他例程不应要求了解该方法的内部工作情况，该方法也不应要求了解它外面的工程情况。这就是为什么你的方法应依靠参数而不应

4、依靠全局变量的原因。创建专用方法时，请考虑下列指导原则：1) 将复杂进程放入专用方法。如果应用程序使用复杂的数学公式，请考虑将每个公式放入它自己的方法中。这样使用这些公式的其他方法就不包含用于该公式的实际代码。这样也可以更容易发现与公式相关的问题。2)将数据输入/输出(I/O)放入专用方法。3) 将专用方法中可能要修改的代码隔离。如果你知道某个进程经常变更，请将这个多变的代码放入专用方法，以便以后可以更容易的进行修改，并减少无意中给其他进程带来问题的可能性。4) 将业务规则封装在专用方法中。业务规则常属于要修改的代码类别，应与应用程序的其余部分隔开。其他方法不应知道业务规则，只有要调用的方法才

5、使用这些规则。1.3. 设计类和方法时，要达到下列目的：1) 创建更加容易调试和维护的方法2) 创建具有强大内聚力的类3) 创建高度专用的方法4) 创建松散连接的方法5) 尽量使方法具有独立性6) 提高方法的扇入性7) 降低方法的扇出性1.4. 编程原则1.4.1. 为方法和类赋予表义性强的名字为了使代码更加容易理解，最容易的方法之一是为你的方法赋予表义性强的名字。函数名DoIt 、 GetIt 的可读性很难与CalculateSalesTax 、 RetrieveUserID 相比。由缩写方法名组成的代码很难理解和维护，没有理由再这样做了。给方法正确的命名，可使程序工程的调试和维护工作大大的

6、改观。请认真对待方法命名的工作，不要为了减少键入操作量而降低方法的可理解度。实际应用举例：1) 给方法命名时应大小写字母混合使用。如果句子全使用大写字母，那么阅读起来就非常困难，而大小写字母混合使用的句子，阅读起来就很容易。2) 定义方法名时不要使用缩写。如果你认为应用程序中的某些工程应使用缩写，那么请将这些情况加上注释，并确保每个人在所有时间内都使用这些缩写。决不要在某些方法中对某些单词进行缩写，而在别的方法中却不使用缩写。3) 定义方法名要统一使用英文单词或者计算机专业英语，要做到见名知意。1.4.2. 创建方法时，始终都应显式地定义它的作用域。1) 如果你真的想创建一个公用方法，请向代码

7、阅读者说明这一点。2) 通过为每个方法赋予一个明确定义的作用域，可以减少代码阅读者需要投入的工作量。应确保你为方法赋予最有意义的作用域。如果一个方法只被同一类中的另一个方法调用，那么请将它创建成私有方法。如果该方法是从多个类中的多个方法中调用，请将该说明为公用方法。1.4.3. 用参数在方法之间传递数据应尽量避免使用类变量。一般来说，变量的作用域越小越好。为了减少类变量，方法之一是将数据作为参数在不同方法之间传递，而不是让方法共享类变量。1) 为每个参数指定数据类型。2) 始终要对数进行检验，决不要假设你得数据没有问题。程序员常犯的一个错误是在编写方法时假设数据没有问题。在初始编程阶段，当编写

8、调用方法时，这样的假设并无大碍。这时你完全能够知道什么是参数的许可值，并按要求提供这些值。但如果你不对参数的数据进行检验，那么下列情况就会给你带来很大麻烦：另外某个人创建了一个调用方法，但此人不知道允许的值；你在晚些时候添加了新的调用方法，并错误的传递了坏数据。1.4.4. 其他编程建议1. 注意释放资源，如文件关闭，数据库操作后关闭ResultSet, Statement, Connection 等， 其他涉及 IO 操作的如:各种Reader， Writer， InputStream ， OutputStream 等等。2. 使用 StringBuffer 对象在处理 String 的时候

9、要尽量使用StringBuffer 类， StringBuffer 类是构成String 类的基础。 String 类将 StringBuffer 类封装了起来，(以花费更多时间为代价)为开发人员提供了一个安全的接口。当我们在构造字符串的时候，我们应该用StringBuffer 来实现大部分的工作，当工作完成后将StringBuffer 对象再转换为需要的String 对象。 比如： 如果有一 个字符串必须不断地在其后添加许多字符来完成构造，那么我们应该使用StringBuffer 对象和它的append() 方法。 如果我们用String 对象代替StringBuffer 对象的话，会花费许

10、多不必要的创建和释放对象的CPU 时间。3. 避免太多的使用synchronized 关键字避免不必要的使用关键字synchronized,应该在必要的时候再使用它，这是一个避免死锁的好方法。必须使用时，也尽量控制范围，最好在块级控制。4. 避免使用java.util.Vector 等那些在jdk1.3 前就有的集合类因为 "Unlike the new collection implementations, Vector is synchronized." ，所以使用 java.util.Vector 类在性能上会有所减低。5. 尽量使用接口而不是一个具体的类比方如下需求

11、，给定一个SQL 语句，返回一个对象的列表，实现中用java.util.ArrayList实现，于是定义方法为：public java.util.ArrayList getObjectItems(String sql)上面的方法存在一个问题，当getObjectItems 内改用 Vector 或 LinkedList 实现，外部类必须做相应更改。一个更好的方法是定义返回值为java.util.AbstractList 更合适：public java.util.AbstractList getObjectItems(String sql) 这样即使更改实现，外部类也不必做相应更改。6. 避免使

12、用索引来调用数据库中间层组件返回的结果集 如：for(int i=1; i<=dt.getRowCount(); i+) String fieldl = dt.getField(i, 0).toString(); 而应用字段名来存取结果集：for(int i=1; i<=dt.getRowCount(); i+) String fieldl = dt.getField(i, "field1").toString(); 这样在数据库设计更改或查询的SQL 语句发生变化时，不会影响到程序的执行。3. 命名约定所有变量的定义应该遵循匈牙利命名法，由表意性强的一个单词或

13、多个单词组成的名字，而且每个单词的首写字母大写，其它字母小写，这样保证了对变量名能够进行正确的断句。3.1. 工程的命名3.1.1. 工程的命名直接使用projectname.3.1.2. 工程目录的分配(参照各类开发工具的设置)1. 设计文档(design)： design2. 源代码(source)： src.3. 引用的库文件(library) ： lib4. 生成的代码(class)： classes5. 生成的文档(document) ： docs3.2. 包3.2.1. 约定根级目录以com.* 开头！(即：实现主要流程的类和涉及项目系统各项目名称为下一级包！本级目录为项目的控制类

14、所在管理的类)。再下级的主要并列目录名：1) Cloudframework 云存储开发框架包2) Cngi 具体的应用系统名全部小写使用英语单词，不要使用汉语拼音标识符用点号分隔开来3.2.2. 举例3.3. 类，接口3.3.1. 约定类的名字应该使用名词使用英语单词，不要使用汉语拼音每个单词首字母 应该大写避免使用单词的缩写，除非它的缩写已经广为人知，如HTTP实现类一般采用接口类名+Impl 来展现3.3.2. 举例Class Hello;Class HelloWorld ;Interface Apple;Class AppleImpl implements Apple;3.4. 方法3.

15、4.1. 约定第一个单词一般是动词。使用英语单词，不要使用汉语拼音第一个单词是小写，但是中间单词的首字母是大写。bool如果方法返回一个成员变量的值，方法名一般为get+ 成员变量名，如若返回的值是变量，一般以is 作为前缀。如果方法修改一个成员变量的值，方法名一般为：set+ 成员变量名。3.4.2. 举例getName();setName();isFirst();3.5. 变量3.5.1. 约定单词的首字母大写；但是首个单词字母都必须小写使用英语单词，不要使用汉语拼音不要用_或 &作为第一个字母。尽量使用短而且具有意义的单词。单字符的变量名一般只用于生命期非常短暂的变量。i,j,k

16、,m,n 一般用于int/integers ；c,d,e 一般用于characters 。如果变量是集合，则变量名应用复数。boolean/ Boolean 类型的使用is 前缀命名组件采用匈牙利命名法。3.5.2. 举例String fileName;int students;int i;int n;boolean isPass;3.6. 常量3.6.1. 约定所有常量名均全部大写，单词间以_隔开。使用英语单词，不要使用汉语拼音特殊情况下可以使用全拼，但是请注释说明3.6.2. 举例int I_MAX_NUM;3.7. jsp,html,xml 等文件3.7.1. 约定使用英语单词，不要使用

17、汉语拼音首单词小写，其它单词首字母 应该大写避免使用单词的缩写，除非它的缩写已经广为人知，如HTTP3.7.2. 举例注册，新增查询页面视图维护页面视图按日期查询页面视图register.jsp view.jsp infoMaintain.jsp dateView.jsp3.8. 数据库表、视图3.8.1. 约定全部小写以“_”分隔单词尽量表义使用英语单词，不要使用汉语拼音主表用“ info ”表示，每个表名都加“t_ ”用来识别为表对象3.8.2. 举例t_user_info缩写ui 用户主表t_user_type用户类型字典表3.9. 数据库字段3.9.1. 约定首单词小写，其他单词首字母

18、大写使用英语单词，不要使用汉语拼音3.9.2. 举例id name userType userId4. 使用常量4.1. 常数很容易在数据输入时出错常数存在的主要问题之一是你很容易在键入数字时出错，从而颠倒了数字的位置。例如，当你键入数字10876 时，很容易的键入10867 或18076。与处理变量和保留字的方法不同，编译器并不在乎颠倒了位置和不正确的数字，有时简单的错误造成的问题不会立即表现出来，而当问题表现出来时，它们会以随机的计算错误的形式出现，这些错误很难准确定位。用常量来取代常数时，编译器将在编译时检查常量的有效性。如果常量不存在，编译器便将这一情况通知你，并拒绝进行编译，这可以消

19、除错误键入的数字带来的问题，只要常量拥有正确的值，使用该常量的所有代码也有使用该正确值。4.2. 常数很难不断更新4.3. 常量使代码更容易阅读使用常量后，得到的一个额外好处是可使创建的代码更容易阅读。常数很不直观。也许你对常 数非常了解，但其他人则根本看不明白。通过合理的给常量命名，使用这些常量的代码就变得 比较直观了，更容易阅读。为常量赋予较宽的作用域，这与使用变量时的情况不同。在一个应用程序中你决不应该两次创 建相同的常量。如果你发现自己复制了一个常量，请将原始的常量说明转至较宽的作用域，直 到该常量可供引用它的所有方法为止。5. 变量5.1. 定义有焦点的变量用于多个目的的变量称为无焦

20、点（多焦点）的变量。无焦点变量所代表的意义与程序的执行流程有关，当程序处于不同位置时，它所表示的意义是不固定的，这样就给程序的可读性和可维护性带来了麻烦。5.2. 只对常用变量名和长变量名进行缩写如果需要对变量名进行缩写时，一定要注意整个代码中缩写规则的一致性。例如，如果在代码的某些区域中使用 Cnt,而在另一些区域中又使用Count,就会给代码增加不必要的复杂性变量名中尽量不要出现缩写。5.3. 使用统一的量词通过在结尾处放置一个量词，就可创建更加统一的变量，它们更容易理解，也更容易搜索。例如 ， 请 使 用 strCustomerFirst 和 strCustomerLast ， 而 不

21、要 使 用 strFirstCustomer 和 strLastCustomer 。量词列表：First 、 Last 、 Next、 Prev、 Cur量词后缀说明First 一组变量中的第一个Last 一组变量中的最后一个Next 一组变量中的下一个变量Prev 一组变量中的上一个Cur 一组变量中的当前变量5.4. 使用肯定形式的布尔变量给布尔变量命名时，始终都要使用变量的肯定形式，以减少其它开发人员在理解布尔变量所代表的意义时的难度。5.5. 为每个变量选择最佳的数据类型这样即能减少对内存的需求量，加快代码的执行速度，又会降低出错的可能性。用于变量的数据类型可能会影响该变量进行计算所产

22、生的结果。在这种情况下，编译器不会产生运行期错误，它只是迫使该值符合数据类型的要求。这类问题极难查找。5.6. 尽量缩小变量的作用域如果变量的作用域大于它应有的范围，变量可继续存在，并且在不再需要该变量后的很长 时间内仍然占用资源。它们的主要问题是，任何类中的任何方法都能对它们进行修改，并且很难跟踪究竟是何处 进行修改的。占用资源是作用域涉及的一个重要问题。对变量来说，尽量缩小作用域将会对应用程序的 可靠性产生巨大的影响。6. 代码的格式化6.1. 对代码进行格式化时，要达到的目的1. 通过代码分割成功能块和便于理解的代码段，使代码更容易阅读和理解；2. 使用空行和注释行，将程序中逻辑上不相关

23、的代码块分开。比如：变量声明部分和代码语句间的分隔；较长的方法中，完成不同功能的代码块间的分隔。要避免出现逻辑上混乱的分隔，如：某一逻辑功能代码块中间用空行进行了分隔，但是在相邻功能代码块之间却没有分隔，这样会给程序阅读者造成错觉。3. 减少为理解代码结构而需要做的工作；4. 使代码的阅读者不必进行假设；5. 使代码结构尽可能做到格式清楚明了。6.2. 编程原则1. 不要将多个语句放在同一行上。不论是变量声明，还是语句都不要在一行上书写多个。2. 缩进后续行当你将变量设置为某个值时，所有后续行的缩进位置应与第一行的变量值相同；当你调用一个方法时，后续行缩进到第一个参数的开始处；当你将变量或属性

24、设置为等于表达式的计算结果时，请从后面分割该语句，以确保该表达式尽可能放在同一行上。3. 在 if 语句后缩进；在 else 语句后缩进在 switch 语句后缩进在 case 语句后缩进在do句后缩进已经用行接续符分割的语句的各个行要缩进对从属于行标注的代码进行缩进。4. 在执行统一任务的各个语句组之间插入一个空行。好的代码应由按逻辑顺序排列的进程或相关语句组构成。7. 代码的注释7.1. 使用代码注释的目的1. 文字说明代码的作用（即为什么要用编写该代码, 而不是如何编写）;2. 确指出该代码的编写思路和逻辑方法;3. 方便人们注意到代码中的重要转折点;4. 使代码的阅读者不必在他们的头脑

25、中仿真运行代码的执行方法.5. 说明代码的使用条件。7.2. 编程原则7.2.1. 用文字说明代码的作用:简单的重复代码做写什么, 这样的注释几乎不能给注释增加什么信息. 如果你使用好的命名方法来创建直观明了的代码那么这些类型的注释绝对增加不了什么信息.7.2.2. 如果你想违背好的编程原则,请说明为什么有的时候你可能需要违背好的编程原则，或者使用了某些不正规的方法，. 遇到这种情况时, 请用内部注释来说明你在做什么和为什么要这样做。技巧性特别高的代码段，一定要加详细的注释，不要让其他开发人员花很长时间来研究一个高技巧但不易理解的程序段。7.2.3. 用注释来说明何时可能出错和为什么出错7.2

26、.4. 在编写代码前进行注释给代码加注释的方法之一是在编写一个方法前首先写上注释. 如果你愿意, 可以编写完整句子的注释或伪代码. 一旦你用注释对代码进行了概述, 就可以在注释之间编写代码.7.2.5. 在要注释的代码前书写注释注释一定出现在要注释的程序段前，不要在某段程序后书写对这段程序的注释，先看到注释对程序的理解会有一定帮助。如果有可能，请在注释行与上面代码间加一空行。7.2.6. 纯色字符注释行只用于主要注释注释中要分隔时，请使用一行空注释行来完成，不要使用纯色字符，以保持版面的整洁、清晰。7.2.7. 避免形成注释框用星号围成的注释框，右边的星号看起来很好, 但它们给注释增加了任何信

27、息吗?实际上这会给编写或编辑注释的人增加许多工作。7.2.8. 增强注释的可读性注释是供人阅读的，而不是让计算机阅读的。1) 使用完整的语句。虽然不必将注释分成段落(最好也不要分成段落)，但你应尽量将注释写成完整的句子。2) 避免使用缩写。缩写常使注释更难阅读，人们常用不同的方法对相同的单词进行缩写，这会造成许多混乱，如果必须对词汇缩写，必须做到统一。3) 将整个单词大写，以突出它们的重要性。若要使人们注意注释中的一个或多个单词，请全部使用大写字母。7.2.9. 对注释进行缩进，使之与后随的语句对齐。注释通常位于它们要说明的代码的前面。为了从视觉上突出注释与它的代码之间的关系，请将注释缩进，使

28、之与代码处于同一个层次上。7.2.10. 为每个方法和类赋予一个注释标头每个方法都应有一个注释标头。方法的注释标头可包含多个文字项，比如输入参数、返回值、原始作者、最后编辑该方法的程序员、上次修改日期、版权信息。7.2.11. 当行尾注释用在上面这种代码段结构中时，它们会使代码更难阅读。使用多个行尾注释时(比如用于方法顶部的多个变量说明)，应使它们互相对齐。这可使它们稍容易阅读一些。7.2.12. 何时书写注释1) 请在每个if 语句的前面加上注释。2) 在每个 switch 语句的前面加上注释。与if 语句一样，switch 语句用于评估对程序执行产生影响的表达式。3) 在每个循环的前面加上

29、注释。每个循环都有它的作用，许多情况下这个作用不清楚直观。7.3. 注释那些部分7.3.1. 类类的目的参数：参数类型参数用来做什么任何约束或前提条件已知的问题类的开发/ 维护历史注释出采用的不变量并行策略编译单元每一个类/ 类内定义的接口，含简单的说明文件名和/ 或标识信息版权信息7.3.2. 接口目的它应如何被使用以及如何不被使用7.3.3. 类属性用处目的不同值的含义7.3.4. 成员函数注释成员函数做什么以及它为什么做这个哪些参数必须传递给一个成员函数成员函数返回什么已知的问题任何由某个成员函数抛出的异常可见性决策成员函数是如何改变对象的包含任何修改代码的历史如何在适当情况下调用成员函

30、数的例子适用的前提条件和后置条件7.3.5. 成员函数内部注释控制结构代码做了些什么以及为什么这样做局部变量 难或复杂的代码 处理顺序对 if-else 语句的各个条件，要说明其含义。7.4. 示例7.4.1. 块注释：主要用来描述文件，类，方法，算法等。一般用在文档和方法的前面，也可以放在文档的任何地方。以/* 开头， */ 结尾。例： /* 注释*/7.4.2. 行注释：主要用在方法内部，对代码，变量，流程等进行说明。与块注释格式相似，但是整个注释占据 一行。例： /* 注释 */7.4.3. 尾随注释：与行注释功能相似，放在代码的同行，但是要与代码之间有足够的空间，便于分清。例：int

31、m=4 ;/*注释 */如果一个程序块内有多个尾随注释，每个注释的缩进应该保持一致。7.4.4. 行尾注释：与行注释功能相似，放在每行的最后，或者占据一行。以/ 开头。7.4.5. 文档注释：与块注释相似，但是可以被 javadoc处理，生成HTM戊件。以'/* '开头，'*/ '结尾。文档 注释不能放在方法或程序块内。例：/*注释*/. 表达式和语句1.1. 每行应该只有一条语句。1.2. if-else,if-elseif 语句，任何情况下，都应该有“”， “ ”，格式如下：if (num1>10 && isOK=true )state

32、ment;else if (condition)statements;else statements;1.3. for 语句格式如下：for (initialization; condition; update)statements;如果语句为空：for (initialization; condition; update) ;1.4. while 语句格式如下：while (condition) statements; 如果语句为空while (condition);1.5. do-while 语句格式如下：dostatements; while (condition);1.6. switc

33、h 语句，每个switch 里都应包含default 子语句 ,格式如下：switch (condition) case ABC: statements;/* falls through */case DEF: statements; break;case XYZ: statements; break;default:statements;break;1.7. try-catch 语句格式如下：try statements;catch （ExceptionClass e）statements;finallystatements;9. 错误处理和异常事件9.1. 法则通常的思想是只对错误采用异常处理：逻辑和编程错误，设置错误，被破坏的数据，资源耗尽，等等。通常的法则是系统在正常状态下以及无重载和硬件失效状态下，不应产生任何异常。9.2. 方法异常处理采用日志机制来报告异常（调用系统LOG4J妾口统一管理），包括异常发生的时刻。不要使用异常实现来控制程序流程结构。每一个类或文件都要处理异常或错误。9.3. 异常封装Dao层的类中统一封装所有异常为DBExceptionService 层的类统一获取底层的DBException 封装为 Bu