JAVA代码编写规范.doc

JAVA 代码编写规范代码编写规范 文件标识： ACEWAY-JAVA-CODE-CONVENTION.doc 当前版本：2.0 作 者：钟波清、黄承宇 完成日期： 文件状态： 草稿 正式发布 正在修改 保密级别：机密 公司名称： 北京汉铭信通科技有限公司 公司地址： 北京市朝阳区安翔北里 11 号创业大厦 B 座 11 层 邮政编码： 100101 公司网址： WWW.ACEWAY.COM.CN 联系电话：传 真：JAVA 代码编写规范 北京汉铭信通科技有限公司 北京市朝阳区安翔北里 11 号创业大厦 B 座 11 层 邮编：100101 电话：传真： 1 ACEWAY-JAVA-CODE- CONVENTION.doc 修改记录修改记录 日期日期版本版本作者作者/修改者修改者描述描述审核人审核人 2006-03-141.0钟波清新建文档 2012-07-022.0黄承宇更新文档、调整章节、增加 Eclipse 模板文件 JAVA 代码编写规范 北京汉铭信通科技有限公司 北京市朝阳区安翔北里 11 号创业大厦 B 座 11 层 邮编：100101 电话：传真： 2 ACEWAY-JAVA-CODE- CONVENTION.doc 目目 录录 1.1.引言引言 3 3 .目的目的 3 3 .适用范围适用范围 3 3 .参考资料参考资料 3 3 .缩略语和术语缩略语和术语 3 3 2.2.规范描述规范描述 4 4 .字符编码字符编码 4 4 .命名规定命名规定 4 4 .2.1.包的命名包的命名 5 5 .2.2.类或接口命名类或接口命名 5 5 .2.3.常量命名常量命名 6 6 .2.4.变量命名变量命名 6 6 .2.5.方法命名方法命名 7 7 .2.6.数组命名数组命名 7 7 .格式格式 7 7 .3.1.缩进缩进 7 7 .3.2.空格空格 ( (建议建议) ) 8 8 .3.3.行宽行宽 9 9 .3.4.花括号花括号 ( (建议建议) ) 1111 .3.5.空行（建议）空行（建议） 1111 .3.6.EclipseEclipse 格式模板格式模板 1313 .注释注释 1414 .4.1.类的注释类的注释 1515 .4.2.EclipseEclipse 代码模板代码模板 1616 .编程惯例编程惯例 1818 JAVA 代码编写规范 北京汉铭信通科技有限公司 北京市朝阳区安翔北里 11 号创业大厦 B 座 11 层 邮编：100101 电话：传真： 3 ACEWAY-JAVA-CODE- CONVENTION.doc 1. 引言引言 1.1.目的目的 为编码活动中提供统一标准的编码规范，便于将来对代码文件的审查、管理工作。 1.2.适用范围适用范围 用于编码过程中 JAVA 代码的编写规范。 1.3.参考参考资料资料 资料名称资料名称标识符标识符出版单位出版单位作者作者日期日期 CodeConventions.pdfCodeConventions.pdfSun1997.9.12 1.4.缩略语和术语缩略语和术语 缩写缩写原文原文中文释意中文释意 JAVA 代码编写规范 北京汉铭信通科技有限公司 北京市朝阳区安翔北里 11 号创业大厦 B 座 11 层 邮编：100101 电话：传真： 4 ACEWAY-JAVA-CODE- CONVENTION.doc 2. 规范描述规范描述 2.1.字符编码字符编码 Java 源代码文件采用 UTF-8 字符编码，JavaDOC 也采用 UTF-8 字符编码。 建议新建项目或 Check Out 项目后，第一个操作先修改项目的编码配置。或者修改 Eclipse 的全局配置，默认项目使用 UTF-8 编码。 输出 JavaDOC 时，增加“-encoding UTF-8 -charset UTF-8”配置，防止文档内容乱 码。如图： 2.2.命名规定命名规定 命名总则： 使用“见名知义”的名称。如：age、name。 使用熟悉的名称或者适用于相关领域的术语。如：SQLAdapter、HTMLCreator。 尽量不使用缩写，而使用完整的英文描述符。如：sgntr，很难知道它是否为 signature。 使用大家基本可以理解的缩写，避免使人产生误解。如：temp 可缩写为 JAVA 代码编写规范 北京汉铭信通科技有限公司 北京市朝阳区安翔北里 11 号创业大厦 B 座 11 层 邮编：100101 电话：传真： 5 ACEWAY-JAVA-CODE- CONVENTION.doc tmp；flag 可缩写为 flg；statistic 可缩写为 stat；increment 可缩写为 inc；message 可缩写为 msg。 不要使用相似的名称，或者仅仅以大小写不同来区分的名称。 不要使用超过 20 个字母长度的名称。 在不能遵循本命名规范的代码中，一定要在代码中以文档注释格式说明命名的 中文名称和含义。如：“/* dishi:地市，三级区域代称 */” 。 2.2.1.包的命名包的命名 包名应该是小写的单词或者单词缩写。前缀一般是： 一个顶级域名，通常是 com、edu、gov、mil、net、org； 1981 年 ISO3166 标准所指定的标识国家的英文双字符代码。如 cn； 一个能够表明该包的用途的单词或者单词缩写。 包名的后续部分根据不同机构各自内部的命名规范而不尽相同。这类命名规范可能 以特定目录名的组成来区分部门、项目、机器或注册名。 例如： package com.aceway.eoms.workflowcom.aceway.eoms.workflow; package cn.acewaycn.aceway; package java.iojava.io; 2.2.2.类或接口命名类或接口命名 采用“帕斯卡（pascal）命名法” ，首字母大写，混合使用大小写字母命名。 接口命名一般采用以大写字母”I”开头的，如果多个字母，每个单词的头字母要大 写。 接口实现类的命名是将实现的接口名称的首字母“I”去掉，以“Impl”作为结尾， 如果是多个单词，每个单词的首字母要大写。 类名通常是一名词，采用大小写混合的方式，每个单词的首字母大写。类名必须简 洁而富于描述。避免缩写词(除非被广泛使用，如 URL、HTML)。例如： class CustomerAccountCustomerAccount class KeyAdapterKeyAdapter JAVA 代码编写规范 北京汉铭信通科技有限公司 北京市朝阳区安翔北里 11 号创业大厦 B 座 11 层 邮编：100101 电话：传真： 6 ACEWAY-JAVA-CODE- CONVENTION.doc 2.2.3.常量命名常量命名 常量应该全部大写，单词间用下划线隔开。例如： static final int MIN_WIDTHMIN_WIDTH = 4; static final String TRACE_FILETRACE_FILE = “Log_003201538001”; 2.2.4.变量变量命名命名 变量名采用“骆驼命名法” ，必须用一个小写字母开头，后面的单词用大写字母开 头。应简短且富于描述，即能够指出其用途，一般为名词。例如： private Address addressaddress; String userNameuserName; 使用复数形式来命名集合类型。如： Customer customerscustomers = new Customer100; Vector orderItemsorderItems = new Vector(); 避免单个字符的变量名，除非是一次性的临时变量或者一些被广为使用的简写。如： for (int i i = 0; i i 0) i+; / 错误,没有“”和“” if (i 0) i+; / 错误,“”和“”在同一行 if (i 0) / 错误,“”不应单独占一行 i+; if (i 0) i+; / 错误,“”应与“if”对齐 正确如下： if (i 0) i+; 再如： if (i 0) i+; else if (i Formatter 配 置，使用 Import 功能，将模板 XML 文件导入到 Eclipse 里，并选择这个格式化模板 （名称：aceway）作为当前选项。如图： 一般大家都是用快捷键 Ctrl+Shift+F 手动格式化，这样容易遗忘。 Eclipse 里带有自动格式化功能，默认是没有开启该功能的。开启自动格式化功能具 体方法：windowsPreferencesJava EditorSave Actions, 在右侧选项里勾选 JAVA 代码编写规范 北京汉铭信通科技有限公司 北京市朝阳区安翔北里 11 号创业大厦 B 座 11 层 邮编：100101 电话：传真： 14 ACEWAY-JAVA-CODE- CONVENTION.doc “Perform the selected actions on save” ，其他选项根据需要自己选择或者配置就可以了。 2.4.注释注释 Java 程序的注释可以有以下几种类型： 文档注释。文档注释用来描述类、接口、构建器，方法及字段，且应位于声明 之前，以“/*”开始， “*/”结束。文档注释的第一行（“/*” ）要与相应的 声明语句对齐，随后的每行都要再缩进一个空格(使星号纵向对齐)。 标准（或 C 风格）注释。以“/*”开始， “*/”结束。 单行注释。以“/”开始。 以下是一些例子： /* * The Example class provides . */ JAVA 代码编写规范 北京汉铭信通科技有限公司 北京市朝阳区安翔北里 11 号创业大厦 B 座 11 层 邮编：100101 电话：传真： 15 ACEWAY-JAVA-CODE- CONVENTION.doc /* * Here is a block comment. */ if (condition) /* Handle the condition. */ . if (a = 2) return TRUE; /* special case */ else return isPrime(a); /* works only for odd a */ if (foo 1) / Do a double-flip. . else return false; / Explain why here. /if (bar 1) / / / Do a triple-flip. / . JAVA 代码编写规范 北京汉铭信通科技有限公司 北京市朝阳区安翔北里 11 号创业大厦 B 座 11 层 邮编：100101 电话：传真： 16 ACEWAY-JAVA-CODE- CONVENTION.doc / /else / return false; / 注释应被用来给出代码的总括，并提供代码自身没有提供的附加信息，包含了与阅 读和理解程序有关的信息。如果代码已经可以清晰表达出来，就没必要写在注释里。例 如，相应的包如何被建立或位于哪个目录下之类的信息等。 修改代码时也要加注释，并注意同时更新原来的注释，使之保持与代码一致。 另外，注释不应写在用星号或其他字符画出来的大框里，也不应包括诸如制表符和 回退符之类的特殊字符。 注释用中文。 修改时要注释修改时间，修改人名，修改说明 2.4.1.类的注释类的注释 对 Java 类的注释需要增加研发部规范的注释文本块： /* * 文件名称：Main.java * 文件描述： * * 版权声明：(C)2012-2015 * 公司部门：应用集成事业部 研发部 * 创建时间：2012-7-3 * * author 黄承宇 * version 1.0 */ 在“文件描述：”下第一行内（“”前）插入类的说明信息。author 后插入 作者中文姓名，version 后插入类文件的版本号。版本号采用#.#格式编写。 2.4.2.Eclipse 代码模板代码模板 要求使用统一的代码模板来做注释自动生成，模板文件： 。 comment-Templates.xml JAVA 代码编写规范 北京汉铭信通科技有限公司 北京市朝阳区安翔北里 11 号创业大厦 B 座 11 层 邮编：100101 电话：传真： 010-648539