Java 开发规范 代码规范

zfr046 贡献于2012-11-02

作者 awded  创建于2007-03-20 02:31:00   修改者Mark Liu  修改于2012-05-28 08:10:00字数11012

文档摘要:本规范的目的是通过建立编码规范统一每个开发人员的编码习惯,提高程序的可靠性、可读性、可修改性、可维护性及一致性,增加团队合作开发效率,为各项目组之间或项目组内成员之间的技术交流提供一个方便统一的方式。本规范适用于PBN公司内所有运用JAVA技术的软件项目、产品等的设计、开发以及维护、升级等。 本规范适用于公司所有JAVA软件开发人员。 对于代码,最重要的是它必须正确,能够按照设计预定功能去运行;第二是要求代码必须清晰易懂,使软件开发团队中的程序员能够很容易地理解代码。 代码的组织和风格的基本原则是:便于自己的开发,易于与他人的交流。
关键词:

 Java编代码规范 编号:PBN-DEV-001 版本:1.2 太平洋宽频带通讯公司 Java编码规范 编制: 审核: 标审: 批准: Martin Liu © 太平洋宽频带通讯公司版权所有 本文件的所有权属于太平洋宽频带通讯公司,所有员工均具有责任保护本文件在未经授权的情况下不被使用,复制及公开。未经授权,该文件所有内容对外禁止以任何形式使用,复制及公开。 第 页 共 26 页 Java编代码规范 编号:PBN-DEV-001 版本:1.2 修订历史纪录 日期 版次 修订说明 修订人 2007-3-16 1.0 初始创建 韩冬 2007-3-19 1.1 整理修改 刘海旺 2012-5-23 1.2 重新排版整理 刘成城 © 太平洋宽频带通讯公司版权所有 本文件的所有权属于太平洋宽频带通讯公司,所有员工均具有责任保护本文件在未经授权的情况下不被使用,复制及公开。未经授权,该文件所有内容对外禁止以任何形式使用,复制及公开。 第 页 共 26 页 Java编代码规范 编号:PBN-DEV-001 版本:1.2 目 录 1 前言 5 1.1 目的(Objective) 5 1.2 范围(Scope) 5 2 格式规范(FORMATS SPECIFICATIONS) 5 2.1 缩进(Indentation) 5 2.2 换行(Wrapping Lines) 6 2.3 间隔(Space) 6 2.4 对齐(Aligning) 6 3 注释规范(COMMENTS) 6 3.1 基本原则(Principle) 6 3.2 实现注释的格式(Implementation Comment Formats) 6 3.2.1 块注释(Block Comments) 7 3.2.2 单行注释(Single-Line Comments) 7 3.2.3 尾端注释(Trailing Comments) 7 3.2.4 行末注释(End-Of-Line Comments) 8 3.3 文档注释(Documentation Comments) 8 3.4 TODO注释 9 4 命名规范(NAMING SPECIFICATION) 9 4.1 缩写约定(Conventions For Short) 10 4.2 详细命名约定(Detailed Naming Specification) 10 4.3 JSP命名约定(Naming Specification For JSP) 13 5 声明(DECLARATIONS) 13 5.1 每行声明变量的数量(Number Per Line) 13 5.2 初始化(Initialization) 13 5.3 布局(Placement) 14 © 太平洋宽频带通讯公司版权所有 本文件的所有权属于太平洋宽频带通讯公司,所有员工均具有责任保护本文件在未经授权的情况下不被使用,复制及公开。未经授权,该文件所有内容对外禁止以任何形式使用,复制及公开。 第 页 共 26 页 Java编代码规范 编号:PBN-DEV-001 版本:1.2 5.4 类和接口的声明(Class and Interface Declarations) 15 6 语句(STATEMENTS) 15 6.1 简单语句(Simple Statements) 15 6.2 复合语句(Compound Statements) 16 6.3 返回语句(return Statements) 16 6.4 if,if-else,if else-if else 语句(if, if-else, if else-if else Statements) 16 6.5 for 语句(for Statements) 17 6.6 while 语句(while Statements) 17 6.7 do-while 语句(do-while Statements) 17 6.8 switch 语句(switch Statements) 18 6.9 try-catch 语句(try-catch Statements) 18 7 版本控制 19 7.1 代码的版本号 19 7.2 模块的版本号 19 8 附录 20 © 太平洋宽频带通讯公司版权所有 本文件的所有权属于太平洋宽频带通讯公司,所有员工均具有责任保护本文件在未经授权的情况下不被使用,复制及公开。未经授权,该文件所有内容对外禁止以任何形式使用,复制及公开。 第 页 共 26 页 Java编代码规范 编号:PBN-DEV-001 版本:1.2 1 前言 1.1 目的(Objective) 本规范的目的是通过建立编码规范统一每个开发人员的编码习惯,提高程序的可靠性、可读性、可修改性、可维护性及一致性,增加团队合作开发效率,为各项目组之间或项目组内成员之间的技术交流提供一个方便统一的方式。 1.2 范围(Scope) 本规范适用于PBN公司内所有运用JAVA技术的软件项目、产品等的设计、开发以及维护、升级等。 本规范适用于公司所有JAVA软件开发人员。 本规范建议的开发环境与工具如下: IDE:XXXXXX版本 插件:XXXXXX版本 JDK: Sun JDK 1.X 2 格式规范(Formats Specifications) 对于代码,最重要的是它必须正确,能够按照设计预定功能去运行;第二是要求代码必须清晰易懂,使软件开发团队中的程序员能够很容易地理解代码。 代码的组织和风格的基本原则是:便于自己的开发,易于与他人的交流。 因个人习惯和编辑器等可以设置和形成自己的风格,但必须前后一致,并符合本规范的基本要求和原则。 2.1 缩进(Indentation) 尽量避免一行的长度超过100 个字符,注意:用于文档中的例子应该使用更短的行长,长度一般不超过70 个字符。 © 太平洋宽频带通讯公司版权所有 本文件的所有权属于太平洋宽频带通讯公司,所有员工均具有责任保护本文件在未经授权的情况下不被使用,复制及公开。未经授权,该文件所有内容对外禁止以任何形式使用,复制及公开。 第 页 共 26 页 Java编代码规范 编号:PBN-DEV-001 版本:1.2 2.2 换行(Wrapping Lines) 当一个表达式无法容纳在一行内时,可以依据如下一般规则断开之: 1.在一个逗号后面断开 2.在一个操作符前面断开 3.宁可选择较高级别(higher-level)的断开,而非较低级别(lower-level)的断开 4.新的一行应该与上一行同一级别表达式的开头处对齐 5.如果以上规则导致你的代码混乱或者使你的代码都堆挤在右边,那就代之以缩进8个空格。 2.3 间隔(Space) 类、方法及功能块间等应以空行相隔,以增加可读性,但不得有无规则的大片空行。操作符两端应当各空一个字符以增加可读性。相应独立的功能模块之间可使用注释行间隔,并标明相应内容。 2.4 对齐(Aligning) 关系密切的行应对齐,对齐包括类型、修饰、名称、参数等各部分对齐。连续赋值时应当对齐操作符。当方法参数过多时在适当的参数后(逗号后)换行并对齐。当控制或循环中的条件比较长时当换行(操作符前)、对齐并注释各条件。 3 注释规范(Comments) 3.1 基本原则(Principle) 注释应该增加代码的清晰度。代码注释的目的是要使代码更易于被其他开发人员等理解。 注释信息不仅要包括代码的功能,还应给出原因。 除变量定义等较短语句的注释可用行尾注释外,其他注释当避免使用行尾注释。 3.2 实现注释的格式(Implementation Comment Formats) 程序可以有4 种注释的风格:块(block)、单行(single-line)、尾端(trailing)和行末(end-of-line)。 © 太平洋宽频带通讯公司版权所有 本文件的所有权属于太平洋宽频带通讯公司,所有员工均具有责任保护本文件在未经授权的情况下不被使用,复制及公开。未经授权,该文件所有内容对外禁止以任何形式使用,复制及公开。 第 页 共 26 页 Java编代码规范 编号:PBN-DEV-001 版本:1.2 3.2.1 块注释(Block Comments) 块注释通常用于提供对文件,方法,数据结构和算法的描述。块注释被置于每个文件的开始处以及每个方法之前。它们也可以被用于其他地方,比如方法内部。在功能和方法内部的块注释应该和它们所描述的代码具有一样的缩进格式。 推荐 不推荐 /* * This is a block comment. */ /* This is a block comment, but the start * and end are not clear.*/ /* * This is a block comment. * It has multiple lines. */ /* This is a block comment, but there is no indicator on the left margin. */ 3.2.2 单行注释(Single-Line Comments) 短注释可以显示在一行内,并与其后的代码具有一样的缩进层级。如果一个注释不能在一行内写完,就该采用块注释(参见"块注释")。单行注释之前应该有一个空行。 以下是一个Java 代码中单行注释的例子: if (condition) { /* Handle the condition. */ ... } 3.2.3 尾端注释(Trailing Comments) 极短的注释可以与它们所要描述的代码位于同一行,但是应该有足够的空白来分开代码和注释。若有多个短注释出现于大段代码中,它们应该具有相同的缩进。 以下是一个Java 代码中尾端注释的例子: if (a == 2) { return TRUE; /* special case */ } else { return isPrime(a); /* works only for odd a */ © 太平洋宽频带通讯公司版权所有 本文件的所有权属于太平洋宽频带通讯公司,所有员工均具有责任保护本文件在未经授权的情况下不被使用,复制及公开。未经授权,该文件所有内容对外禁止以任何形式使用,复制及公开。 第 页 共 26 页 Java编代码规范 编号:PBN-DEV-001 版本:1.2 } 3.2.4 行末注释(End-Of-Line Comments) 注释界定符"//",可以注释掉整行或者一行中的一部分。它一般不用于连续多行的注释文本;然而,它可以用来注释连续多行的代码段。以下是所有三种风格的例子: if (foo > 1) { // Do a double-flip .... } else { return false; // Explain why here. } //if (bar > 1) { // // // Do a triple-flip. // ... //} //else { // return false; //} 注释应在相应的代码段之前,内容应包括代码功能及参数说明。 3.3 文档注释(Documentation Comments) 文档注释描述Java 的类、接口、构造器,方法,以及字段(field)。每个文档注释都会被置于注释定界符/**...*/之中,一个注释对应一个类、接口或成员。 该注释应位于声明之前: 示例: /** * The Example class provides ... */ © 太平洋宽频带通讯公司版权所有 本文件的所有权属于太平洋宽频带通讯公司,所有员工均具有责任保护本文件在未经授权的情况下不被使用,复制及公开。未经授权,该文件所有内容对外禁止以任何形式使用,复制及公开。 第 页 共 26 页 Java编代码规范 编号:PBN-DEV-001 版本:1.2 Pubic class Example{ …. 注意顶层的类和接口的声明不缩进,而其成员是缩进的,所以描述类和接口的文档注释的第一行(/**)也不需缩进;随后的文档注释每行都缩进1 格(使星号纵向对齐)。成员,包括构造函数在内,其文档注释的第一行缩进4 格,随后每行都缩进5格。 3.4 TODO注释 TODO注释(TODO Comments) 对那些临时的、短期的解决方案,或已经够好但并不完美的代码使用TODO注释。 这样的注释要使用全大写的字符串TODO,后面括号(parentheses)里加上姓名、邮件地址等,还可以加上冒号(colon):目的是可以根据统一的TODO格式进行查找: // TODO(kl@gmail.com): Use a "*" here for concatenation operator. // TODO(Zeke) change this to use relations. 如果加上是为了在“将来某一天做某事”,可以加上一个特定的时间("Fix by November 2005")或事件("Remove this code when all clients can handle XML responses.")。 4 命名规范(Naming Specification) 命名规范使程序更易读,从而更易于理解。它们也可以提供一些有关标识符功能的信息, 以助于理解代码,例如,不论它是一个常量,包,还是类。 通用惯例: 1.使用完整的,能够望文生义的英文 2.使用跟该领域相关的术语 3.大小写混合使用,以增加可读性 4.名称尽量不要超过15个字符 5.不要只用大小写的差异来区分两个变量名称,这样容易造成混淆 避免使用以下划线开头或结尾的定义。但是在应用动态byte code 生成技术修改POJO 类的时候,应考虑使用统一的前缀或尾缀以避免命名冲突。 不应该单纯为了缩减代码长度而减少变量名字的长度,作为命名应首要考虑可读性,应尽量采用可读性强的短语,所以应尽可能使用较长的命名以明确表达含义。具体方法参看具体的类别。 © 太平洋宽频带通讯公司版权所有 本文件的所有权属于太平洋宽频带通讯公司,所有员工均具有责任保护本文件在未经授权的情况下不被使用,复制及公开。未经授权,该文件所有内容对外禁止以任何形式使用,复制及公开。 第 页 共 26 页 Java编代码规范 编号:PBN-DEV-001 版本:1.2 避免使用单个字符(如:i,j,k)命名变量。仅可使用i、j、k 作局部循环变量。如在for 循环中,可使用i, j, k 作循环变量。 4.1 缩写约定(Conventions For Short) 标识符的命名采用含义明确的英文单词,尽量使用完整的单词或易于理解的缩写。除一些公认的缩写形式,应对文件中所使用的个人形式缩写或特殊意义缩写在源文件的开始进行必要的注释说明,并在程序编写中保持一致。 缩写应使用相应的大小写形式,当这些缩写与其他单词组合命名时,应考详细考虑可读性后再进行命名,如:JDBCJNDIName 应改写为JdbcJndiName。 一些公认的缩写形式: ·temp 缩写为tmp ·flag 缩写为flg ·increment 缩写为inc ·message 缩写为msg ·Implementation 缩写为Impl ·Iterator 缩写为itr 4.2 详细命名约定(Detailed Naming Specification) 表3-1 命名约定 标识符 命名约定 示例 Packages Package 的名字由一个小写单词组成。命名方式为:com.pbn.模块名称[.子包名]*。 习惯用法:如果package 提供一系列的抽象接口,则提供缺省实现的子包名为defaults com.pbn.core com.pbn.core.runtime © 太平洋宽频带通讯公司版权所有 本文件的所有权属于太平洋宽频带通讯公司,所有员工均具有责任保护本文件在未经授权的情况下不被使用,复制及公开。未经授权,该文件所有内容对外禁止以任何形式使用,复制及公开。 第 页 共 26 页 Java编代码规范 编号:PBN-DEV-001 版本:1.2 模块的内部服务命名为internal Classes Enums Annotations 类名、枚举名、Annotation 都是一个名词,采用大小写混合的方式,每个单词的首字母大写,尽量使类名简洁而富于描述,使用完整单词,尽量避免缩写词(除非该缩写词被更广泛使用,像URL,HTML),如采用缩写,也应遵循单词首字母大写的方式以增强易读性。 如果类对某一接口提供了基本的实现,且为abstract 类,建议采用Abstract开头,如果是对某一个Abstract 类提供的确省实现,建议采用Default 为开头 类名: class Customer class CustomerAccount class JdbcLoader 枚举名: enum Role Annotation: @interface SecurityTag Interfaces 默认以大写字母I 开头表示定义的型别为interface,I 之后为具体的Interface命名,其规则与类名相同,但除采用名词性的单词之外,也可以使用形容词性的单词。这里不硬性规定接口名称必须以I开头 IDataAccessObject IStorable Method 方法名是一个动词或者动词短语,采用大小写混合的方式,第一个单词的首字母小写,其后单词的首字母大写。不应该单纯为了缩减代码长度而减少 method 名字的长度,作为命名应首要考虑可读性,应尽量以功能描述性短句作为命名。 runThread() getBackgroundColor() Boolean Methods 布尔方法名是一个具有疑问语气的短语,采用大小写混合的方式,如果对单独条件判断,建议采用 isReady() isValidating(Parser p) © 太平洋宽频带通讯公司版权所有 本文件的所有权属于太平洋宽频带通讯公司,所有员工均具有责任保护本文件在未经授权的情况下不被使用,复制及公开。未经授权,该文件所有内容对外禁止以任何形式使用,复制及公开。 第 页 共 26 页 Java编代码规范 编号:PBN-DEV-001 版本:1.2 is 前缀,如果表示查询一个对象集合中是否还有指定的对象,建议采用has 前缀 hasElement(Object o) 变量/参数 变量名是一个名词,所有变量、对象实例均采用大小写混合的方式,第一个单词的首字母小写,其后单词的首字母大写。变量名不应以下划线或美元符号 开头,尽管这在语法上是允许的。作为命名应首要考虑可读性,应尽量采用可读性强的短语。有时对于在代码块中频繁出现的某些类型的变量可以使用一些约定的简写来表示,比如x, y, z 可以用于表示坐标等。 String firstName float creditCharge 常量 常量的名字应该全部采用大写,单词之间用下划线分割,并且指出完整含义。 static final int MIN_WIDTH = 4 static final int MAX_WIDTH = 999 异常变量 采用缩写e 表示,如果是嵌套异常,则使用e1,e2 的命名 catch(IOException e) { } catch(AnException e) { try { } catch (OtherException e1) { } } Get/Set 方法 获取/设置私有成员变量的方法名由前缀get /set + 被访问变量名称组成 private String position; String getPosition(); void setPosition(String position); 聚合类型 当为array 时,采用s 尾缀;当为Collection 时,采用List, Set, Map 等接口做尾缀,而避免采用与实现相关的 String[] customerNames ArrayList customerNameList © 太平洋宽频带通讯公司版权所有 本文件的所有权属于太平洋宽频带通讯公司,所有员工均具有责任保护本文件在未经授权的情况下不被使用,复制及公开。未经授权,该文件所有内容对外禁止以任何形式使用,复制及公开。 第 页 共 26 页 Java编代码规范 编号:PBN-DEV-001 版本:1.2 Vector, ArrayList, HashMap, Hashtable 等做尾缀 Vector customerNameList Collection customerNameCollection Generic 如果采用泛型,泛型声明为一个大写的字母,如:T、E 之类。 Class Generic 4.3 JSP命名约定(Naming Specification For JSP) JSP页面的命名原则上遵循命名的通用规范(除第三条外);比如增加用户的页面: user_add.jsp,列出用户的页面user_list.jsp;全部使用小写, 使用”_”分隔。 JSP 文件目录组织原则上应该按照功能模块放在相应的目录下。 5 声明(Declarations) 5.1 每行声明变量的数量(Number Per Line) 推荐一行一个声明,因为这样以利于写注释。亦即, int level; // indentation level int size; // size of table 5.2 初始化(Initialization) 尽量在声明局部变量的同时初始化。 例如: void someMethod() { int maxConnection = 10; Foo someFoo = new Foo(); Foo otherFoo = null; © 太平洋宽频带通讯公司版权所有 本文件的所有权属于太平洋宽频带通讯公司,所有员工均具有责任保护本文件在未经授权的情况下不被使用,复制及公开。未经授权,该文件所有内容对外禁止以任何形式使用,复制及公开。 第 页 共 26 页 Java编代码规范 编号:PBN-DEV-001 版本:1.2 } 唯一不这么做的理由是变量的初始值依赖于某些先前发生的计算。 5.3 布局(Placement) 只在代码块的开始处声明变量。(一个块是指任何被包含在大括号"{"和"}"中间的代码。)不要在首次用到该变量时才声明之。这会使程序不易读懂,同时会妨碍代码在该作用域内的可移植性,但是,要尽量保持变量的作用域最小。 注意:在可以保证代码质量与可读性的前提下可灵活掌握该规则 例如: void myMethod() { int int1 = 0; // beginning of method block if (condition) { int int2 = 0; // beginning of "if" block ... } } 该规则的一个例外是for 循环的索引变量 for (int i = 0; i < maxLoops; i++) { ... } 避免声明的局部变量覆盖上一级声明的变量。例如,不要在内部代码块中声明相同的变量名: int count; ... myMethod() { if (condition) { int count = 0; // AVOID! ... } ... } © 太平洋宽频带通讯公司版权所有 本文件的所有权属于太平洋宽频带通讯公司,所有员工均具有责任保护本文件在未经授权的情况下不被使用,复制及公开。未经授权,该文件所有内容对外禁止以任何形式使用,复制及公开。 第 页 共 26 页 Java编代码规范 编号:PBN-DEV-001 版本:1.2 5.4 类和接口的声明(Class and Interface Declarations) 当编写类和接口时,应该遵守以下格式规则: - 在方法名与其参数列表之前的左括号"("间不要有空格; - 左大括号"{"位于声明语句同行的末尾; - 右大括号"}"另起一行,与相应的声明语句对齐,除非是一个空语句,"}"应紧跟在"{"之后。 class Sample extends Object { int ivar1; int ivar2; Sample(int i, int j) { ivar1 = i; ivar2 = j; } int emptyMethod() {} ... } - 方法与方法之间以空行分隔 6 语句(Statements) 6.1 简单语句(Simple Statements) 每行至多包含一条语句,例如: argv++; //正确 argc--; //正确 argv++; argc--; //避免 © 太平洋宽频带通讯公司版权所有 本文件的所有权属于太平洋宽频带通讯公司,所有员工均具有责任保护本文件在未经授权的情况下不被使用,复制及公开。未经授权,该文件所有内容对外禁止以任何形式使用,复制及公开。 第 页 共 26 页 Java编代码规范 编号:PBN-DEV-001 版本:1.2 6.2 复合语句(Compound Statements) 复合语句是包含在大括号中的语句序列,形如"{ 语句}"。例如下面各段。 - 被括其中的语句应该较之复合语句缩进一个层次; - 左大括号"{"应位于复合语句起始行的行尾;右大括号"}"应另起一行并与复合语句首行对齐。 - 大括号可以被用于所有语句,包括单个语句,只要这些语句是诸如if-else 或for 控制结构的一部分。这样便于添加语句而无需担心由于忘了加括号而引入bug。 6.3 返回语句(return Statements) 一个带返回值的return 语句不使用小括号"()",除非它们以某种方式使返回值更为显见。例如: return; return myDisk.size(); return (size ? size : defaultSize); 6.4 if,if-else,if else-if else 语句(if, if-else, if else-if else Statements) if-else 语句应该具有如下格式: if (condition) { statements; } if (condition) { statements; } else { statements; } if (condition) { statements; © 太平洋宽频带通讯公司版权所有 本文件的所有权属于太平洋宽频带通讯公司,所有员工均具有责任保护本文件在未经授权的情况下不被使用,复制及公开。未经授权,该文件所有内容对外禁止以任何形式使用,复制及公开。 第 页 共 26 页 Java编代码规范 编号:PBN-DEV-001 版本:1.2 } else if (condition) { statements; } else{ statements; } 注意:if 语句总是用"{"和"}"括起来,无论statements 中有多少语句 6.5 for 语句(for Statements) 一个for 语句应该具有如下格式: for (initialization; condition; update) { statements; } 一个空的for 语句(所有工作都在初始化,条件判断,更新子句中完成)应该具有如下格式: for (initialization; condition; update); 当在for 语句的初始化或更新子句中使用逗号时,避免因使用三个以上变量,而导致复杂度提高。若需要,可以在for 循环之前(为初始化子句)或for循环末尾(为更新子句)使用单独的语句。 6.6 while 语句(while Statements) 一个while 语句应该具有如下格式 while (condition) { statements; } 一个空的while 语句应该具有如下格式: while (condition); 6.7 do-while 语句(do-while Statements) 一个do-while 语句应该具有如下格式: do { © 太平洋宽频带通讯公司版权所有 本文件的所有权属于太平洋宽频带通讯公司,所有员工均具有责任保护本文件在未经授权的情况下不被使用,复制及公开。未经授权,该文件所有内容对外禁止以任何形式使用,复制及公开。 第 页 共 26 页 Java编代码规范 编号:PBN-DEV-001 版本:1.2 statements; } while (condition); 6.8 switch 语句(switch Statements) 一个switch 语句应该具有如下格式: switch (condition) { case ABC: statements; /* falls through */ case DEF: statements; break; case XYZ: statements; break; default: statements; break; } 每当一个case 顺着往下执行时(因为没有break 语句),通常应在break 语句的位置添加注释。上面的示例代码中就包含注释/* falls through */。 每个switch 语句应包括一个default 选项。default 选项里的break 是冗余的,但可预防以后增加另一个选项后没有中断执行导致错误的情况出现。 6.9 try-catch 语句(try-catch Statements) 一个try-catch 语句应该具有如下格式: try { statements; } catch (ExceptionClass e) { © 太平洋宽频带通讯公司版权所有 本文件的所有权属于太平洋宽频带通讯公司,所有员工均具有责任保护本文件在未经授权的情况下不被使用,复制及公开。未经授权,该文件所有内容对外禁止以任何形式使用,复制及公开。 第 页 共 26 页 Java编代码规范 编号:PBN-DEV-001 版本:1.2 statements; } 一个try-catch 语句后面也可能跟着一个finally 语句,不论try 代码块是否顺利执行完,它都会被执行。 try { statements; } catch (ExceptionClass e) { statements; } finally { statements; } 7 版本控制 7.1 代码的版本号 代码的版本号主要用以区别不同的类版本,版本号是由用ASCII 字符集中的小数点隔开三个部分组成的,这三部分皆为非负的正整数,并通过其数值的大小标定版本的高低,如下形式皆为有效合法的版本号: 0.1.0 1.2.5 3.1.1234 一个版本号可以在逻辑上划分为主版本号,子版本号,维护版本号这三个组成部分。 7.2 模块的版本号 模块的版本号主要用以区别不同版本的模块,是由用ASCII 字符集中的小数点隔开四个部分组成的,这四部分中的前三个为非负的正整数,并通过其数值的大小标定版本的高低,最后一部分是一个不含空格的由数字、字母还有-组成的字符串。如下形式皆为有效合法的版本号: 1.0.0 © 太平洋宽频带通讯公司版权所有 本文件的所有权属于太平洋宽频带通讯公司,所有员工均具有责任保护本文件在未经授权的情况下不被使用,复制及公开。未经授权,该文件所有内容对外禁止以任何形式使用,复制及公开。 第 页 共 26 页 Java编代码规范 编号:PBN-DEV-001 版本:1.2 1.1.235 1.1.2.RC 1.9(认为是1.9.0) 1.9.Beta(认为是1.9.0.Beta) 3(认为是3.0.0) 3.Alpha(认为是3.0.0.Alpha) 一个模块版本号可以在逻辑上划分为主版本号,子版本号,维护版本号以及版本限定词这四个组成部分。 8 附录 表7-1常用文件后缀 文件类型 后缀名 Java 源文件 .java Java 类文件 .class Java 归档文件 .jar JavaServerPage .jsp Java 标记库文件 .tld Web 应用归档文件 .war 企业应用归档文件 .ear 属性文件 .properties Freemarker Template .ftl Hyper Text Markup Language .html,.htm Dynamic Hyper Text Markup Language .dhtml JavaScript .js Extensible Markup Language .xml © 太平洋宽频带通讯公司版权所有 本文件的所有权属于太平洋宽频带通讯公司,所有员工均具有责任保护本文件在未经授权的情况下不被使用,复制及公开。未经授权,该文件所有内容对外禁止以任何形式使用,复制及公开。 第 页 共 26 页 Java编代码规范 编号:PBN-DEV-001 版本:1.2 Extensible Style Sheet Language .xsl Document Type Definition .dtd XML Schema .xsd 表7-2 常用文件名 文件名 用途 readme.txt 指定文件夹下程序模块的摘要 chagelog.txt 指定文件夹下程序的修改记录 build.xml 指定文件夹下程序编译的ant 脚本 pom.xml 指定项目的maven 脚本 build.properties 指定项目的ant 脚本属性描述 checkstyle.xml 指定项目的checkstyle 描述 .classpath eclipse IDE 项目配置文件 .project eclipse IDE 项目配置文件 .tomcatplugin eclipse Tomcat Plugin Web 项目配置文件 基本文件目录结构 7-3源代码目录 源代码目录必须在properties à Java Build Path à Source 里面设置。 /src/java 项目Java 源码 /src/resources 项目配置文件 /test/unit 项目Unit 测试源码 /test/functional 项目Functional 测试源码 /test/resources 项目测试所需配置文件 7-4Build目录 Build 目录为执行ant 脚本、发布项目所需要的目录。 /lib 执行Ant 脚本所需的jar 包目录 /database 项目数据库脚本目录 © 太平洋宽频带通讯公司版权所有 本文件的所有权属于太平洋宽频带通讯公司,所有员工均具有责任保护本文件在未经授权的情况下不被使用,复制及公开。未经授权,该文件所有内容对外禁止以任何形式使用,复制及公开。 第 页 共 26 页 Java编代码规范 编号:PBN-DEV-001 版本:1.2 /build/release 发布项目目录 /build/lib 执行项目测试所需要的特殊jar 包目录 /build/bin Unit 测试源码编译路径 7-5 web目录 默认的web 目录为/webapps /webapps/css 项目css 文件目录 /webapps/js js 文件目录 /webapps/images 图片目录 表7-6注释样例 注释项 注释内容 文件头 参见3.1.1 文件注释 类 参考样式: /** * 功能摘要 *

* 独立于具体实现方法的API 描述,包括:行为约束,条件约束,实现约束, * 对于一些对线程敏感的类,需要明确指出其线程安全性 *

* 对于较复杂的类给出该类应用的示范代码 * * @author 开发者姓名 * @version 版本号 * @since 能够使用该类的产品的最小版本号 */ 接口 参考样式: /** © 太平洋宽频带通讯公司版权所有 本文件的所有权属于太平洋宽频带通讯公司,所有员工均具有责任保护本文件在未经授权的情况下不被使用,复制及公开。未经授权,该文件所有内容对外禁止以任何形式使用,复制及公开。 第 页 共 26 页 Java编代码规范 编号:PBN-DEV-001 版本:1.2 * 功能摘要 *

* 独立于具体实现方法的API 描述,包括:行为约束,条件 约束,实现约束,对于一些对线 * 程敏感的类,需要明确指出其对实现的线程安全性约束 *

* 对于较复杂的接口给出该类应用的示范代码 * * @author 开发者姓名 * @version 版本号 * @since 能够使用该类的产品的最小版本号 */ 方法 参考样式: /** * 功能摘要 *

* 独立于具体实现方法的API 描述,包括:行为约束,条件 约束,实现约束 * * @param 参数名简单描述 * @return 返回值描述 * @throws 异常发生异常情况的描述 */ 局部变量 参考样式: //局部变量的含义及用途 局部变量声明 常量 参考样式: //常量的含义及用途 常量定义 © 太平洋宽频带通讯公司版权所有 本文件的所有权属于太平洋宽频带通讯公司,所有员工均具有责任保护本文件在未经授权的情况下不被使用,复制及公开。未经授权,该文件所有内容对外禁止以任何形式使用,复制及公开。 第 页 共 26 页 Java编代码规范 编号:PBN-DEV-001 版本:1.2 算法注释 参考样式: //代码段目的,算法步骤的含义 代码段 修改注释 参考样式 /* * 版本号 * 修改前的代码 */ 新的替换代码 © 太平洋宽频带通讯公司版权所有 本文件的所有权属于太平洋宽频带通讯公司,所有员工均具有责任保护本文件在未经授权的情况下不被使用,复制及公开。未经授权,该文件所有内容对外禁止以任何形式使用,复制及公开。 第 页 共 26 页

下载文档到电脑,查找使用更方便

文档的实际排版效果,会与网站的显示效果略有不同!!

需要 10 金币 [ 分享文档获得金币 ] 1 人已下载

下载文档