JAVA开发编码规范1.2.doc

1、江苏亿科达科技发展有限公司1/18江苏亿科达科技发展有限公司JAVA 开发编码规范江苏亿科达科技发展有限公司2/18版 本 说 明版本 制订人 制订日期 主要内容V1.0 夏霆 2008-09-11 JAVA 开发编码规范初稿V1.1 田路 2008-10-31 JAVA 开发编码规范修改V1.2 夏霆 2008-10-31 确认发布江苏亿科达科技发展有限公司3/18一、 前言 .31.1、 目的 .31.2、范围 .4二、 格式规范 .42.1 缩进 .52.2 换行 .52.3 间隔 .52.4 对齐 .52.5 括号 .5三、注释规范 .63.1 基本原则 .63.2 文件注释 .63.

2、3 Java Doc 注释 .63.4 失效代码注释 .73.5 代码细节注释 .73.6 注释的格式 .83.7 注释的内容 .83.8 Null 规约 .84 命名规范(Naming Conventions).94.1 基本约定 .104.2 文件、包 .104.3 类、接口 .104.4 字段 .105 编程规范(Programming Conventions) .115.1 基本规范 .115.2 类与接口 .125.3 方法 .125.4 错误与异常 .135.5 JDK5.0 及后续版本 .145.6 性能与安全 .146 自动代码检查和修正 .156.1 为了编码的一致性，统一将

3、 Workspace 中的编码方式设置为 UTF-8 编码 .156.2 使用统一的代码模板 .16江苏亿科达科技发展有限公司4/18一、 前言1.1、 目的本规范的目的是通过建立编码规范统一每个开发人员的编码习惯，提高程序的可靠性、可读性、可修改性、可维护性及一致性，增加团队合作开发效率，为各项目组之间或项目组内成员之间的技术交流提供一个方便统一的方式。1.2、范围本规范适用于公司内所有运用 JAVA 技术的软件项目、产品等的设计、开发以及维护、升级等。本规范适用于公司所有 JAVA 软件开发人员。本规范建议的开发环境与工具如下：IDE:Eclipse3.3.2 以后版本插件:MyEclip

4、se6.0 以后版本JDK: Sun JDK 1.5江苏亿科达科技发展有限公司5/18二、 格式规范对于代码，首要要求是它必须正确，能够按照设计预定功能去运行；第二是要求代码必须清晰易懂，使软件开发团队中的程序员能够很容易地理解代码。代码的组织和风格的基本原则是：便于自己的开发，易于与他人的交流。因个人习惯和编辑器等可以设置和形成自己的风格，但必须前后一致，并符合本规范的基本要求和原则。2.1 缩进使用 TAB 缩进，而不是空格键将缩进 2，4，8 字符的选择权留给阅读者。子功能块当在其父功能块后缩进。当功能块过多而导致缩进过深时当将子功能块提取出来做为子函数。2.2 换行页宽应该设置为 80

5、 字符。一般不要超过这个宽度, 这会导致在某些机器中或打印（A4）时无法以一屏来完整显示 , 但这一设置也可以灵活调整。在任何情况下 , 超长的语句应该在一个逗号后或一个操作符。前折行。一条语句折行后, 应该比原来的语句再缩进一个 TAB，以便于阅读。2.3 间隔类、方法及功能块间等应以空行相隔，以增加可读性，但不得有无规则的大片空行。操作符两端应当各空一个字符以增加可读性。相应独立的功能模块之间可使用注释行间隔，并标明相应内容。2.4 对齐关系密切的行应对齐，对齐包括类型、修饰、名称、参数等各部分对齐。连续赋值时应当对齐操作符。当方法参数过多时在适当的参数后（逗号后）换行并对齐。当控制或循环

6、中的条件比较长时当换行（操作符前）、对齐并注释各条件。2.5 括号括号中的语句应该单独作为一行，左括号“当紧跟其语句后，右括号“永远单独作为一行且与其匹配行对齐，并尽量在其后说明其匹配的功能模块。较长的方法以及类、接口等的右括号后应使用/end .等标识其结束。如:类的结束符：/end ClassName ，方法结束符：/end methodName()，江苏亿科达科技发展有限公司6/18功能块结束：/end if.userName is null?循环快结束：/end for.every user in userList不要在程序中出现不必要的括号，但有时为了增加可读性和便于理解，当用括号限

7、定相应项。If，for，while 语句只有单句时，如果该句可能引起阅读混淆，需要用“和“括起来，否则可以省略。三、注释规范3.1 基本原则基本原则：注释应该增加代码的清晰度。代码注释的目的是要使代码更易于被其他开发人员等理解。注释信息不仅要包括代码的功能，还应给出原因。除变量定义等较短语句的注释可用行尾注释外，其他注释当避免使用行尾注释。3.2 文件注释在每个文件、包的头部都应该包含该文件的功能、作用、作者、版权以及创建、修改记录等。并在其中使用版本仓库标记自动跟踪版本变化及修改记录等信息。注意是标准的C-Style/*.*/ 注释而不是/* .*/ 形式的 JavaDoc 注释，在 ECL

8、IPS 中使用 CODE TEMPLATES 会自动添加，如下。/* (#) Test1.java* Created Date: Sep 11, 2008* Copyright (c) Jiangsu Ecode Co., Ltd* This software is the confidential and proprietary information of* Jiangsu Ecode Co., Ltd. (“Confidential Information“). You shall not* disclose such Confidential Information and shall

9、 use it only in accordance* with the terms of the license agreement you entered into with* Jiangsu Ecode Co., Ltd.江苏亿科达科技发展有限公司7/18*/3.3 Java Doc 注释对类、方法、变量等的注释需要符合 JavaDoc 规范，对每个类、方法都应详细说明其功能、条件、参数等，并使用良好的 HTML 标记格式化注释，以使生成的 JavaDoc 易阅读和理解。类注释中当包含版本和作者信息，使用版本仓库的标记自动跟踪版本变化和修改记录，如下。/* 用于示例的类* * autho

10、r Xiating* version $Rev$ * $Id: Test1.java,v 1.2 2008/09/17 02:25:08 cvsroot Exp $*/public class Test1 private static final Logger logger = Logger.getLogger(Test1.class);/*一个测试的方法*param userid 用户编号*return 返回用户信息对象，若无该用户信息，则返回null*/private UserInfo getStrings(Integer userid) return userInfo;3.4 失效代码注

11、释由/*.*/界定，标准的 C-Style 的注释。专用于注释已失效的代码。/*username = “;password = “;currentCar = “;logined = false;attributes = new HashMap();attributes.put(“title“, “hello“);*/江苏亿科达科技发展有限公司8/18失效注释快捷键是 Ctrl+Shift+/ ，取消注释是 Ctrl+Shift+3.5 代码细节注释由/ 界定，专用于注释代码细节，即使有多行注释也仍然使用 /，以便与用/*/注释的失效代码分开除了私有变量外，不推荐使用行末注释。/设置CarBea

12、nfor(int i=0; i 分隔。 示例代码以包裹。 标识(java keyword, class/method/field/argument 名，Constants) 以 包裹。 标识在第一次出现时以linkxxx.Myclass注解以便 JavaDoc 与 IDE 中可以链接。3.7 注释的内容 对于 API 函数如果存在契约，必须写明它的前置条件(precondition) ，后置条件(postcondition)，及不变式(invariant)。 对于调用复杂的 API 尽量提供代码示例。 对于已知的 Bug 需要声明。 在本函数中抛出的 unchecked exception 尽

13、量用throws 说明。 注释中的每一个单词都要有其不可缺少的意义，注释里不写“param name -名字“无意义的内容。江苏亿科达科技发展有限公司9/18 注释的标签必须有内容，不能存在空的param name，空的return。3.8 Null 规约如果方法允许Null 作为参数，或者允许返回值为 Null，必须在 JavaDoc 中说明。如果没有说明，方法的调用者不允许使用Null 作为参数，并认为返回值是Null Safe的。/* * param actionEvent 买车按钮的动作事件* throws Exception 一般异常*/public void buyCar(Acti

14、onEvent actionEvent) throws Exception江苏亿科达科技发展有限公司10/184 命名规范(Naming Conventions)规范的命名能使程序更易阅读，从而更易于理解。它们也可以提供一些标识功能方面的信息，有助于更好的理解代码和应用。4.1 基本约定 使用可以准确说明变量/字段/ 类/接口/ 包等的完整的英文描述符。例如，采用类似firstName，listAllUsers 或 CorporateCustomer 这样的名字，严禁使用汉语拼音及不相关单词命名，虽然 Java 支持 Unicode 命名，但本规范规定对包、类、接口、方法、变量、字段等不得使用

15、汉字等进行命名。 采用该领域的术语。如果用户称他们的“客户”(clients) 为“顾客”(customers)，那么就采用术语 Customer 来命名这个类，而不用 Client。 采用大小写混合，提高名字的可读性。一般应该采用小写字母，但是类和接口的名字的首字母，以及任何中间单词的首字母应该大写。包名全部小写。 尽量少用缩写，但如果一定要使用，当使用公共缩写和习惯缩写等，如实现（implement）可缩写成 impl，应用程序（application ）可缩写成 app 等，严禁滥用缩写。 避免使用长名字（最好不超过 25 个字母）。 避免使用相似或者仅在大小写上有区别的名字。 避免使用

16、数字，但可用 2 代替 to，用 4 代替 for 等，如：go2Jsp。 遇到缩写如 XML 时， 仅首字母大写， 即 loadXmlDocument() 而不是loadXMLDocument()。4.2 文件、包 文件名当与其类严格相同，所有单词首字母大写。 包名一般以项目或模块名命名，少用缩写和长名，一律小写。 基本包：com.candur ，所有包、文件都从属于此包。 包名按规则组成：基本包 . 项目名 . 模块名 . 子模块名. 不得将类直接定义在基本包下，所有项目中的类、接口等都当定义在各自的项目和模块包中。4.3 类、接口所有单词首字母大写。使用能确切反应该类、接口含义、功能等的词。一般采用名词。接口可以可以在名词前加大写I ，如IBookDao, ，BookDaoIF。