软件编码规范(谭波波).doc

软件开发编码规范研发部软件编码规范软件部 谭波波2016年01月文档编号001版本号 总页数26正文 编写 谭波波审查批准生效日期 2016年01月修改记录版本号变更控制报告编号更改条款及内容更改人审批人更改日期目 录1 引言11.1 编写目的11.2 范围12 格式规范22.1 缩进22.2 换行22.3 间隔22.4 对齐22.5 括号23 注释规范43.1 基本原则43.2 类的注释43.3 方法注释43.4 单行注释54 目录结构规范64.1 源码src结构64.2 页面WebRoot 结构75 命名规范(Naming Conventions)95.1 基本约定95.2 文件、包115.3 类、接口、方法125.4 字段125.4.1 常量125.4.2 变量和参数125.4.3 集合136 编程规范146.1 基本规范146.2 类与接口146.2.1 基本原则146.2.2 抽象类与接口146.2.3 继承与组合156.2.4 构造函数和静态工厂方法156.3 方法156.3.1 基本原则156.3.2 参数和返回值156.4 错误与异常156.4.1 基本原则156.4.2 已检查异常与运行时异常166.4.3 异常处理166.4.4 自定义异常166.5 性能与安全176.5.1 String 与StringBugffer176.5.2 集合176.5.3 对象186.5.4 同步186.5.5 final186.5.6 垃圾收集和资源释放187 自动检查和修正197.1 编码方式197.2 代码模板198 数据库编码规范228.1 表命名规范228.2 字段命名规范228.3 JSP 页面命名229 前台页面规范239.1 JSP239.2 Html239.3 JavaScript249.4 CSS2410 编码惯例25261 引言1.1 编写目的编写本文档是旨在制定 “*公司” 的研发部所有开发人员应遵循的编码标准，使编码人员开发的代码更容易维护及理解， 最终目的是节省产品的开发周期，提高项目的开发质量。本文预期读者为：产品开发人员产品测试人员产品维护人员1.2 范围“*公司”研发部各开发人员。2 格式规范对于代码，首要要求是它必须正确，能够按照设计预定功能去运行；第二是要求代码必须清晰易懂，使软件开发团队中的程序员能够很容易地理解代码。代码的组织和风格的基本原则是：便于自己的开发，易于与他人的交流。因个人习惯和编辑器等可以设置和形成自己的风格，但必须前后一致，并符合本规范的基本要求和原则。2.1 缩进使用TAB 缩进，而不是空格键将缩进2，4，8 字符的选择权留给阅读者。子功能块当在其父功能块后缩进。当功能块过多而导致缩进过深时当将子功能块提取出来做为子函数。2.2 换行页宽应该设置为80 字符。一般不要超过这个宽度， 这会导致在某些机器中或打印（A4）时无法以一屏来完整显示， 但这一设置也可以灵活调整。在任何情况下， 超长的语句应该在一个逗号后或一个操作符。前折行。一条语句折行后， 应该比原来的语句再缩进一个TAB，以便于阅读。2.3 间隔类、方法及功能块间等应以空行相隔，以增加可读性，但不得有无规则的大片空行。操作符两端应当各空一个字符以增加可读性。相应独立的功能模块之间可使用注释行间隔，并标明相应内容。2.4 对齐关系密切的行应对齐，对齐包括类型、修饰、名称、参数等各部分对齐。连续赋值时应当对齐操作符。当方法参数过多时在适当的参数后（逗号后）换行并对齐。当控制或循环中的条件比较长时当换行（操作符前）、对齐并注释各条件。2.5 括号括号中的语句应该单独作为一行，左括号当紧跟其语句后，右括号永远单独作为一行且与其匹配行对齐，并尽量在其后说明其匹配的功能模块。不要在程序中出现不必要的括号，但有时为了增加可读性和便于理解，当用括号限定相应项。If，for，while 语句只有单句时，如果该句可能引起阅读混淆，需要用和括起来，否则可以省略。3 注释规范3.1 基本原则基本原则：注释应该增加代码的清晰度。代码注释的目的是要使代码更易于被其他开发人员等理解。注释信息不仅要包括代码的功能，还应给出原因。除变量定义等较短语句的注释可用行尾注释外，其他注释当避免使用行尾注释。3.2 类的注释用于注释整个类，简单概述该类作用。 在注释中要描述该类的基本作用，包含作者，创建日期，版本，公司名称，版权声明、包名、类名，修改时间，修改人，修改的地方等。 例如： 3.3 方法注释用于注释说明类中的方法，简单概述该方法的作用，传入参数的类型及含义，以及该方法的返回值。 例如： 3.4 单行注释用于注释说明某行代码的作用，或某个变量声明时的含义。 例如： 4 目录结构规范4.1 源码src结构序号标识类型对应目录1过滤器类mon.filter2配置文件mon .config3异常类com.hywy. common .exception5监听类mon .listener6Action基类com.hywy. common.action7数据访问基类mon.dao8工具类mon.helper9Action类com.hywy.rainWaterAnalysis.action10数据库操作com.hywy.rainWaterAnalysis.dao11实体对象com.hywy.rainWaterAnalysis.domain12实体类com.hywy.rainWaterAnalysis.service13视图映射类com.hywy.rainWaterAnalysis.vo14数据传输类com.hywy.rainWaterAnalysis.dto示意图： 4.2 页面WebRoot 结构 Js （Javascript 文件目录） Images （图片目录） Css （样式文件目录） upload （附件） util (工具) error （错误提示页面） WEB-INF 页面子模块 （系统模块）5 命名规范(Naming Conventions)规范的命名能使程序更易阅读，从而更易于理解。它们也可以提供一些标识功能方面的信息，有助于更好的理解代码和应用。5.1 基本约定 使用可以准确说明变量/字段/类/接口/包等的完整的英文描述符。例如，采用类似firstName，listAllUsers 或CorporateCustomer 这样的名字，严禁使用汉语拼音及不相关单词命名，虽然Java 支持中文命名，但本规范规定对包、类、接口、方法、变量、字段等不得使用汉字等进行命名。 采用该领域的术语。如果用户称他们的“客户”(clients) 为“顾客”(customers)，那么就采用术语Customer 来命名这个类，而不用Client。 采用大小写混合，提高名字的可读性。一般应该采用小写字母，但是类和接口的名字的首字母，以及任何中间单词的首字母应该大写，包名全部小写。 尽量少用缩写，但如果一定要使用，当使用公共缩写和习惯缩写等，如实现（implement）可缩写成impl，应用程序（application）可缩写成app 等，严禁滥用缩写，采用num作为number的缩写，那么在整个代码中应该始终使用该缩写。 避免使用长名字（最好不超过25 个字母）。 避免使用相似或者仅在大小写上有区别的名字。 避免使用数字，但可用2 代替to，用4 代替for 等，如：go2Jsp。 标识符只能由26个英文字母，10个数字，及下划线的一个子集来组成，并严格禁止使用连续的下划线。因为 variable_name 和 variable_name 很难区分 程序中不要出现仅靠大小写区分的相似的标识符。程序中不要出现仅靠大小写区分的相似的标识符。 获取器方法返回值是boolean型的要以”is”，”have”，”can”，”has”打头，提高代码可读性。 用”is”，”have”，”can”，”has”打头的方法必须返回boolean型 使用习惯的变量命名规则，增强代码的维护性。5.2 文件、包 文件名当与其类严格相同，所有单词首字母大写。 包名一般以项目或模块名命名，少用缩写和长名，一律小写。 包名按规则组成：com . hywy .项目名. 模块名 . 子模块名. package语句后用空行和import语句分隔开。不同类别的import语句之间用空行分隔。 不得将类直接定义在基本包下，所有项目中的类、接口等都当定义在各自的项目和模块包中。5.3 类、接口、方法所有单词首字母大写。使用能确切反应该类、接口含义、功能等的词。一般采用名词。接口可以在名词前加大写I，如IExamApply，IUser。类名首字母应该大写，方法的首字母应小写。对于所有标识符，其中包含的所有单词都应紧靠在一起，不要使用“_”符号连接，而且大写中间单词的首字母。例如：5.4 字段5.4.1 常量所有字母大写，如果有多个单词组成，单词与单词之间以 ” _“ 隔开。而且该变量必须是公共public、静态 static、final类型。例如： 5.4.2 变量和参数对不易清楚识别出该变量类型的变量应使用类型缩写作其前缀，如字符串使用strXXX，boolean 使用isXXX，hasXXX 等等。除第一各个单词外其余单词首字母大写。对私有实例变量可使用下划线“_”前缀，但在其存取方法中则应该将其前缀去掉。局部变量及输入参数不要与类成员变量同名(get/set 方法与构造函数除外)5.4.3 集合一个集合，例如数组，应采用复数命名来表示队列中存放的对象类型。命名应采用完整的英文描述符，名字中所有非开头的单词的第一个字母应大写，适当使用集合缩写前缀。6 编程规范基本原则是遵守Java 语言规范，并遵从习惯用法。6.1 基本规范 当面对不可知的调用者时，方法需要对输入参数进行校验，如不符合抛出IllegalArgumentException，建议使用Spring 的Assert 系列函数。 隐藏工具类的构造器，确保只有static 方法和变量的类不能被构造实例。 变量，参数和返回值定义尽量基于接口而不是具体实现类。 代码中不能使用System.out.println()，e.printStackTrace()，必须使用logger 打印信息。6.2 类与接口6.2.1 基本原则 类的划分粒度，不可太大(类不要超过2000行，方法不要超过100行)，造成过于庞大的单个类，也不可太细，从而使类的继承太深。一般而言，一个类只做一件事；另一个原则是根据每个类的职责进行划分，比如用User 来存放用户信息，而用UserDAO 来对用户信息进行数据访问操作（比如存取数据库），用UserManager来封装用户信息的业务操作等等。 多使用设计模式，随时重构。 多个类中使用相同方法时将其方法提到一个接口中或使用抽象类，尽量提高重用度。 将不希望再被继承的类声明成final，例如某些实用类，但不要滥用final，否则会对系统的可扩展性造成影响。 将不希望被实例化的类的缺省构造方法声明成private。6.2.2 抽象类与接口一般而言：接口定义行为，而抽象类定义属性和公有行为，注意两者间的取舍，在设计中，可由接口定义公用的行为，由一个抽象类来实现其部分或全部方法，以给子类提供统一的行为定义。 多使用接口，尽量做到面向接口的设计，以提高系统的可扩展性。6.2.3 继承与组合尽量使用组合来代替继承，一则可以使类的层次不至于过深，而且会使类与类，包与包之间的耦合度更小，更具可扩展性。6.2.4 构造函数和静态工厂方法当需要使用多个构造函数创建类时，建议使用静态工厂方法替代这些构造方法。6.3 方法6.3.1 基本原则一个方法只完成一项功能，在定义系统的公用接口方法外的方法应尽可能的缩小其可见性。避免用一个类是实例去访问其静态变量和方法。避免在一个较长的方法里提供多个出口。6.3.2 参数和返回值避免过多的参数列表，尽量控制在5 个以内，若需要传递多个参数时，当使用一个容纳这些参数的对象进行传递，以提高程序的可读性和可扩展性。参数类型和返回值尽量接口化，以屏蔽具体的实现细节，提高系统的可扩展性。例如：6.4 错误与异常6.4.1 基本原则通常的思想是只对错误采用异常处理：逻辑和编程错误，设置错误，被破坏的数据，资源耗尽等等。常的法则是系统在正常状态下以及无重载和硬件失效状态下，不应产生任何异常。对于经常发生的可预计事件不要采用异常。不要使用异常实现控制结构。确保状态码有一个正确值。在本地进行安全性检查，而不是让用户去做。若有finally 子句，则不要在try 块中直接返回，亦不要在finally 中直接返回。6.4.2 已检查异常与运行时异常已检查异常必须捕捉并做相应处理，不能将已检查异常抛到系统之外去处理。对可预见的运行时异常当进行捕捉并处理，比如空指针等。通常，对空指针的判断不是使用捕捉NullPointException 的方式，而是在调用该对象之前使用判断语句进行直接判断。6.4.3 异常处理重新抛出的异常必须保留原来的异常，即throw new NewException(message，e); 而不能写成throw new NewException(message)。在所有异常被捕获且没有重新抛出的地方必须写日志，避免异常的湮没。如果属于正常异常的空异常处理块必须注释说明原因，否则不允许空的catch块。框架尽量捕获低级异常，并封装成高级异常重新抛出，隐藏低级异常的细节。多个异常应分别捕捉并处理，避免使用一个单一的catch 来处理。6.4.4 自定义异常为了适应项目业务的需要，可以定义扩展自Exception的异常，在业务类中手动抛出自定义异常，并在控制层中进行捕获。例如：6.5 性能与安全6.5.1 String 与StringBugffer不要使用如下String 初始化方法：String str = new String(“abcdef”);这将产生两个对象，应当直接赋值：String str = “abcdef”;在处理可变String 的时候要尽量使用StringBuffer 类，StringBuffer 类是构成String 类的基础。String 类将StringBuffer 类封装了起来，（以花费更多时间为代价）为开发人员提供了一个安全的接口。当我们在构造字符串的时候，我们应该用StringBuffer 来实现大部分的工作，当工作完成后将StringBuffer 对象再转换为需要的String 对象。比如：如果有一个字符串必须不断地在其后添加许多字符来完成构造，那么我们应该使用StringBuffer 对象和她的append() 方法。如果我们用String 对象代替StringBuffer 对象的话，将会花费许多不必要的创建和释放对象的CPU 时间。6.5.2 集合避免使用Vector 和HashTable 等旧的集合实现，这些实现的存在仅是为了与旧的系统兼容，而且由于这些实现是同步的，故而在大量操作时会带来不必要的性能损失。在新的系统设计中不当出现这些实现，使用ArrayList 代替Vector，使用HashMap 代替HashTable。6.5.3 对象避免在循环中频繁构建和释放对象。不再使用的对象应及时销毁。如无必要，不要序列化对象6.5.4 同步在不需要同步操作时避免使用同步操作类，如能使用ArrayList 时不要使用Vector。尽量少用同步方法，避免使用太多的synchronized 关键字。尽量将同步最小化，即将同步作用到最需要的地方，避免大块的同步块或方法等。6.5.5 final 将参数或方法声明成final 可提高程序响应效率，故此： 注意绝对不要仅因为性能而将类、方法等声明成final，声明成final 的类、方法一定要确信不再被继承或重载！ 不需要重新赋值的变量（包括类变量、实例变量、局部变量）声明成final。 私有(private)方法不需要声明成final。 若方法确定不会被继承，则声明成final。6.5.6 垃圾收集和资源释放不要过分依赖JVM 的垃圾收集机制，因为你无法预测和知道JVM 在什么时候运行GC。尽可能早的释放资源，不再使用的资源请立即释放。可能有异常的操作时必须在try 的finally 块中释放资源，如数据库连接、IO 操做。7 自动检查和修正7.1 编码方式为了编码的一致性，统一将Workspace中的编码方式设置为UTF-8编码图6.1-17.2 代码模板首先，需要加载指定的代码模板，打开Code Templates后选择Comments，再点击Import，将jsecode_eclipse_codetemplates.xml模板导入。图6.2-1次，在创建类或者接口的时候需要勾选 Generate comments图6.2-2代码模板导入之后，请修改注释中的作者部分，改写为您自己的联系方式和名称。8 数据库编码规范8.1 表命名规范采用(hy_模块_表)的命名方式，例如运维管理系统，针对用户，角色，模块，权限有如下几张表hy_sys_modulehy_ sys _groupshy_ sys _rolemodulehy_ sys _roleshy_ sys _roleuserhy_ sys _usergroupshy_ sys _userinfohy_ sys _users8.2 字段命名规范 字段名称不能使用中文，需要使用英文进行命名，英文名太长，按照缩写习惯进行缩写，一个系统中的同一个字段的英文命名必须统一。8.3 JSP 页面命名 所有jsp页面名称要以小写字母开头，如果有多个单词组成，后面的单词以大写字母开头。 名称要体现出该页面的意义，最好能够与模块名称联系在一起。(表_模块_操作或表模块操作)例如： river_Manage_Add.jsp、river_Manage_Update.jsp -在信息维护模块中,对河流表的添加页面更新页面 Jsp页面要求分模块进行管理，不同模块的jsp页放在不同的文件夹里。 考虑到jsp页面的安全性，建议把jsp根目录放到WEB-INF下。9 前台页面规范1、 原则上不允许有java语言代码。2、 不允许直接调用业务逻辑层组件，不能有任何业务逻辑代码。3、 字符集必须为UTF-8。4、 为了方便代码复用，减少重复代码，原则上不允许有任何页面样式的代码，所有字体、颜色、大小等都必须由css文件控制。并且Javascript脚本代码写在js文件中,在页面引入。9.1 JSP1、多个页面共用的部分（如：页头和页脚）应该提取为单独的 jsp 文件，然后在各个使用到该部分代码的页面用 将对应的代码包含进来。2、引入其他 jsp 文件的时候，尽量使用指令引入，如果需要动态的传入参数，才考虑使用 jsp 动作进行引入。3、能用 EL 表达和 jsp 标签实现的，尽量避免使用 这样的Java脚本代码。4、jsp 文件中引入 java 类的时候，为了提高代码的可读性，尽量每引入一个类单独占用一行。9.2 Html1、每个HTML页面的第一行必须为 DOCTYPE 声明，告知浏览器解析CSS的模式，以免页面在各个浏览器中显示的效果不一样。2、尽量使用 DIV 进行布局，而不要使用 Table 嵌套 Table 的形式进行页面布局。3、给Table、TD等元素指定宽度和高度时，应该使用样式进行指定，而不是使用元素的 width 和 height 属性进行指定。4、页面内元素的嵌套必须为一一对应。5、给元素内的文字内容的四周添加空白区域禁止使用   和 ，而应该改为使用元素的 padding 样式进行控制。9.3 JavaScript1、多个页面共用的 javascript 方法必须提取为单独的 js 文件，禁止在每个页面中写一个相同方法。2、方法和变量的命名必须有实际意义，禁止命名为类似于 aaa、bbb 的名称。3、 尽量避免使用原生的js对页面元素进行操作，改为采用jquery替代。9.4 CSS1、多个页面共用的样式，必须提取为单独的 css 文件。2、css 文件中的样式类名称必须有实际意义，禁止使用类似于STYLE1、STYLE2 的名称进行命名。3、css文件中止使用 tagName tagName （如 div div） 这样的选择器，应该将其改为 #id tagName或 。class tagName 这样的形式。4、css 文件中选择器的排序：元素选择器 类选择器 id选择器。10 编码惯例1、 每天上班时，从 SVN 获取最新代码；下班前，必须将测试通过的功能模块代码提交至 SVN 版本库。提交