国家重点XXX项目-代码开发规范.doc

附件四国家发展改革委网上办公系统二期项目代码开发规范编制单位：北京AAAA信息产业股份有限公司编 制 人：编制日期：二一一年四月目 录第1章前言11.1 目的11.2 内容11.3 定义21.4 适用范围2第2章JAVA源码编写规范22.1 标识符的命名规范22.2 公认的命名约定32.3 源文件注释的规范32.3.1 Java中的注释类型32.3.2 历史信息说明42.3.3 类头部注释42.3.4 变量常量注释52.3.5 方法头部注释52.3.6 代码注释52.4 文档排版的规范62.4.1 缩进62.4.2 空格和空行62.4.3 页面宽度72.4.4 长参数表达式的换行72.4.5 括号的匹配82.4.6 import语句8第3章JSP源代码规范93.1 页面目录结构93.2 文件命名规范103.3 HTML文件样式113.4 使用标签代替Java编码123.5 表单显示规范123.6 缩进和对齐133.7 注释143.8 JavaScript文件14第1章 前言1.1 目的为规范国家发展改革委网上办公系统二期项目（以下简称“发改委二期项目）系统的开发代码管理，特制定开发代码规范。通过该规范，我们希望达到以下目标：1. 增加开发过程代码的强壮性、可理解性、易维护性；减少有经验和无经验开发人员编程所需的脑力工作；2. 在项目范围内统一代码风格；3. 使新的开发人员快速适应项目氛围；4. 更好的完成发改委二期项目的开发，以及后期的维护。1.2 内容本规范采用与国际代码规范基本一致的代码规范，并使得能在开发阶段将代码规范落实到项目组中的每一个有关人员。统一代码开发规范，提高代码的质量和可维护性。提供事务、异常处理、文件处理等标准服务，规范各模块的处理方法。制订代码开发规范，撰写核心代码规格及单元测试指针以建立测试导向的开发目标。本规范包括对以下两个部分的规范要求：Java源文件和JSP源文件。将JSP单独提出作为一部分加以规范，目的是为了让JSP源代码符合SUN提出的标准，而不是像一个Java文件。规范主要分为以下几个个方面：1. 手工编写代码时需要注意的部分，如命名和注释；2. 代码排版时需要注意的部分，如缩进，换行等。这一部分可通过编辑器辅助实现；3. 其它的一些问题，如某些技巧和常用解决方案。1.3 定义本规范是针对Java语言的，采用以下的术语描述：1. 规范：编程时强制必须遵守的原则。2. 约定：被大家广泛认同的一些规范。3. 建议：编程时必须加以考虑的原则。4. 说明：对此规则或建议进行必要的解释。5. 示例：对此规则或建议给出的例子。1.4 适用范围适用于国家发展改革委网上办公系统二期项目建设。第2章 JAVA源码编写规范 2.1 标识符的命名规范1. 特殊用途的文件使用表示其用途的后缀，如*Test.java，*Temp.java。2. 使用可以自说明(含义清晰)的英文描述符，如firstName。3. 循环里的简单递增（减）变量可以被命名为 “i”，其它地方不允许这样。4. 尽量采用项目所涉及领域的术语，并且保留一份术语的中英对照表。5. 必要时可以使用汉语拼音缩写(尽量避免)。6. 采用大小写混合，提高名字的可读性。7. 尽量少用缩写，但大家都认可的缩写除外。8. 缩写词语的所有字母都必须大写。9. 严禁使用下划线作为名字的首末字母，如_name， name_。10. 严禁使用数字，如arg0，arg1等说明：如果对命名有不明白的地方，可以参考JDK的源代码。建议：考虑到大多数Java开发者的习惯，尽量不要使用匈牙利命名法。2.2 公认的命名约定类型命名约定示例包全部小写。标识符用点号分隔开来。全局包的名字用你的机构的 Internet 保留域名开头 ject类，接口类的名字应该使用名词。每个单词第一个字母应该大写。避免使用单词的缩写，除非其缩写已广为人知，如HTTPClass Hello ;Class HelloWorld ;Interface Apple ;方法第一个单词一般是动词第一个字母是小写，但是中间单词的第一个字母是大写Getter方法名一般为getXxx()，其中xxx应该和变量名相同，但首字母大写，如若返回的值是boolean变量，一般以is作为前缀。Setter方法名一般为：set Xxx(xxx)。doSomeThing()getName();setName(String name);isFirst();setFirst(boolean first)变量第一个字母小写，中间单词的第一个字母大写。必须使以字母开始，而不是_或$。如果变量是集合，则变量名应用复数。String myName;int students;常量所有常量名均全部大写，单词间以_隔开。使用static final修饰常量。int MAX_NUM;建议：Getter/Setter方法，尽量使用编辑器提供的自动生成功能。对于自动生成的Getter/Setter方法中的参数，可以使用简单的命名方法，如单字母。2.3 源文件注释的规范2.3.1 Java中的注释类型1. 块注释：主要用来描述文件，类，方法，算法等。一般用在文档和方法的前面，也可以放在文档的任何地方。以/*开头，*/结尾。2. 行注释：主要用在方法内部，对代码，变量，流程等进行说明。与块注释格式相似，但是整个注释占据一行。3. 尾随注释：与行注释功能相似，放在代码的同行，但是要与代码之间有足够的空间，便于分清。例：int m=4 ;/*注释*/4. 行尾注释：与行注释功能相似，放在每行的最后，或者占据一行。以/开头。5. 文档注释：与块注释相似，但是可以被javadoc处理，生成HTML文件。以/*开头，*/结尾。文档注释不能放在方法或程序块内。2.3.2 历史信息说明对已经比较稳定的源代码进行修改之后，需要在包声明的位置之前进行标注。内容包括日期，人员和修改的内容。对于多次修改的历史信息，必须按照日期进行逆序排列。2.3.3 类头部注释必须使用文档注释来说明当前类的作用，注意事项等信息。如果是一个公用的工具类，还应该提供起到指导作用的示例代码。类注释中，根据具体情况，还应包含作者，版权等信息。版权信息统一规定如下，版权信息置于作者信息之后：* author作者姓名银拓信息技术有限公司 版权所有2.3.4 变量常量注释并不是所有的变量都需要注释。如果需要对一个变量进行注释，必须在变量定义的上方，而不允许使用尾随注释或者行尾注释。这样做的原因是为了排版的美观。2.3.5 方法头部注释必须使用文档注释说明当前方法的用途和注意事项。如果有参数，必须使用正确的javadoc标签列出该方法需要的每一个参数的名称和说明。如果参数名称比较清晰，可以不提供说明，但是必须有这个标签。如果有返回值或者要抛出异常，也必须在注释中标记。建议：尽量使用编辑器提供的自动生成功能，当然，内容要你自己动手。说明：对于简单的Getter/Setter方法，在名称含义清晰的情况下，可以不提供注释的内容，但是要有javadoc的标示(以后有必要可以加注释)。2.3.6 代码注释代码中的注释必须放在被解释的代码上方，并且两者之间不能有空行。2.4 文档排版的规范2.4.1 缩进代码必须采用缩进的格式进行书写。缩进的长度设置成4个空格。类和方法的开始、结构的定义及循环、判断等语句中的代码都要采用缩进风格，case语句下的情况处理语句也要遵从语句缩进要求。建议：使用TAB键进行缩进，这样可以减少敲键的数量，大多数编辑器的缩进空格数是可以调整的。2.4.2 空格和空行在两个以上的关键字、变量、常量进行对等操作时，它们之间的操作符之前、之后或者前后要加空格。1. 逗号、分号只在后面加空格。2. 比较操作符, 赋值操作符=、 +=，算术操作符+、%，逻辑操作符&、&，等双目操作符的前后加空格。3. !、+、-、等单目操作符前后不加空格。4. if、for、while、switch等与后面的括号间应加空格，使if等关键字更为突出明显。相对独立的程序块之间应该加一行空行。如果每一个对立部分的长度很短（仅有一两个方法调用），各个部分之间可以使用注释进行区分，这种情况不需要空行。2.4.3 页面宽度页面的宽度设置成80个字符。2.4.4 长参数表达式的换行1. 当一条语句中的参数过多，在一行之内无法写完的情况下，应该把每一个参数单独写在一行。2. 当连续出现多个调用的时候，如果不能在一行写完，应该把每一个调用单独写在一行。说明：在使用编辑器的自动排版时，实际生成的代码可以有不一致。2.4.5 括号的匹配1. 代码中所有的大括号都应该采用左对齐的方式。2. 当一对大括号中间没有代码的时候，左右括号之间不能有空行。3. 对于if， while等语句，在任何时候都应该使用大括号。2.4.6 import语句1. 对于代码引用的每一个类，都应有准确的导入语句。2. 不能导入没有使用的类。3. 尽量不要使用*号。4. Java标准包中的类和其它外部包之间应该使用空行隔离。建议：满足上述条件的简便方法，请用带有auto imports功能或者organize imports功能的编辑器。这些编辑器可以自动添加相应的语句，或把你手工输入的*号转化成如上图的格式。第3章 JSP源代码规范对于JSP来说，规范并不多，因为针对于JSP的自动排版工具很少。总的规则就是一句话JSP文件中不要嵌入大量的Java代码，否则可读性将迅速下降。另外，本章将会给出几个基本的规则。以美观为主的页面风格应该参照界面设计规范，不属于这个规范所述的范畴。3.1 页面目录结构在一个应用中，所有jsp页面都存放在应用根路径的jsp目录下，下面的描述以此目录为根。1. 所有的页面文件根据不同的模块，在根目录下分别建目录存放；2. 页面所涉及的所有图片及其他一些资源（如flash动画等）都存放在/images目录下；3. 页面所使用的js文件都存放在/js目录下；4. 页面所使用的风格文件都放在/css下。示例：以下是一个应用的目录分布示例，此应用的jsp文件按模块分为普通版（common）和专业版（expert）两各目录：/-common/-PAG2000301.JSP-PAG2000302.JSP.-expert/-PAG3000301.JSP-PAG3000302.JSP.-images/-LOGO.GIF-BANNER.GIF.-js/-VALIDATE.JS-EBANK.JS.-css/-EBANK.CSS-TABLE.CSS.3.2 文件命名规范在一个应用项目中，页面文件及其相关的资源文件一般数量都比较大，如果没有规律的命名方法，查找和理解都将比较困难，所以这里给出一些命名上应遵守的规范和要注意的问题：1. 文件名（包括页面文件名和图片文件名）必须注意大小写，引用处的大小写必须严格与引用文件名的大小写相同，这样不管在大小写敏感的系统上，还是在大小写不敏感的系统上都不会出错。示例：在页面中引用的某张图片PAG2003010.jsp：在images的目录下，定义图片文件/images-Banners.jpg在文件的里引用时不能用banners.jpg或BANNERS.JPG，必须象上文中那样引用2. 被程序引用的JSP页面，文件名统一以PAG开头，后面跟页面对应的交易码，最后以.jsp结尾。示例：对外转帐交易，交易码为TX2030101：第一步（选择卡折号）使用的页面定义为：PAG2030101.jsp第二步（输入转帐信息）使用的页面定义为：PAG2030102.jsp第三步（确认转帐信息）使用的页面定义为：PAG2030103.jsp3. 图片文件名最好用有意义的名称，统一存放在images目录下，不用的图片要及时删除。3.3 HTML文件样式所有HTML类型文件（包括jsp扩展名和html扩展名）在文件头的“”标识前面必须用“”标识出本页面的使用信息和版权信息：示例：如果是jsp页面，页面“”标识前有标识的，此信息放在标识后面。页面必须有完整的“”结构，在标签里，必须有标识和标识 。页面的统一的风格文件（.css）和脚本文件（.js）的导入，都放在标签后面。示例：欢迎登陆网上银行页面内容3.4 使用标签代替Java编码使用标签书写JSP，可以避免页面中嵌入大量的逻辑处理代码。第一，页面美观便于修改。第二，把逻辑处理封装到后台实现，避免逻辑暴露在JSP文件中。下图中的标签实现了if-else语句的功能。3.5 表单显示规范页面中，表单主要用于提交用户数据到服务端，用户数据的检查是表单的主要任务，所以在页面中，数据检查的代码数量颇多。对这些代码的管理也是规范的要求。1. 页面中用于检查数据是否为空或数据类型是否正确的代码，必须尽可能的抽取公共函数，并将这些公共函数放在统一的文件中。2. 在格式化表单数据的表格中，数据项的名称必须右对齐，并跟“：”号；表单的输入控件（如文本输入框，选择框等）必须左对齐，并且这些控件的长度最好保持一致。示例：3. 文本输入框中允许输入的字符长度必须以这个数据的定义长度为限。最好不要在提交的时候检查长度。示例：最好用maxlength定义最大可输入的字符：如果最大数不是固定的，可用：而不要用以下方式（除非万不得以）：4. 表单提交必须有限制多次提交的js代码。防止用户多次连续点击造成一些以外的后果。示例：var formflag=false; function check()if (document.eservice.InAcct.value.length!=13)alert(转入账号只能是13位或16位);return false;if (formflag) return false;formflag=true;return true; 3.6 缩进和对齐JSP页面中会有大量的标签需要嵌套，所以缩进和对齐特别重要。缩进长度设置为2个空格或者4个空格。位于不同行的开始标签和结束标签应该左对齐。说明：1. 当使用可视化工具生成JSP代码的时候，自动生成的标签对齐格式不做严格要求。2. 重要部分的逻辑处理标签，在和美工不冲突的情况，应该保证格式。3.7 注释JSP中可以嵌入两种形式的注释：html格式和Java格式。应该针对不同的情况选择使用其中之一。1. 当允许注释出现在最终生成的html文件中，使用html格式的注视。2. 当不希望终端用户看到某些注释的情况，应该使用java类型的注视。3.8 JavaScript文件当脚本文件中的函数数量较多的时候，应该单独写成一个文件，而不应该写在JSP文件中。如果只有一两个函数，并且没有重用的必要，就可以内嵌在JSP中。重用的代码应尽量存储到统一