JAVA源代码规范.doc

精选资料 可修改编辑 JAVA 代代码规码规范范 (初稿) 2004.4 精选资料 可修改编辑 版本更新信息版本更新信息 本版本创建/修改、维护、批准涉及人员如下： 创建/修改者：XX 维护者：XX 批准者：XX 具体版本更新记录如表 1-1： 表表 1-1 版本更新版本更新记录记录 版本号 修改确 认日期 修改人修改位置 修改方式 （AMD） 修改内容概述 V1.02004.4 XX全部A初始版本发布 修改方式：修改方式：A增加增加 M修改修改 D删删除除 精选资料 可修改编辑 目的目的 本文提供一整套编写高效可靠的 Java 代码的标准、约定和指南。它们以安全 可靠的软件工程原则为基础，使代码易于理解、维护和增强灵活性。通过遵循一套 通用的程序设计标准，显著提高 Java 软件开发者的生产效率，为开发团队的程序 设计带来更大的一致性，使软件开发团队的效率明显提高。 规规范的范的执执行行 本文档适用于公司内进行软件开发的所有技术人员，即公司内软件开发人员 编写的所有源代码都必须遵循本规范。 除临时性项目之外的任何项目均应严格按照此标准执行， “临时性项目”指： 为市场推广目的而编写的示程序 为一次性用途而编写的临时性小程序 为学习目的而编写的测试程序 文档文档类别类别 本文档属标准规范类的项目限制级文档，未经总经理及总经理授权人员批准， 不得提供公司以外的人员阅读和使用。 版本更新条件版本更新条件 本文档的定期评审时间为每年的 1 月，评审及修订步骤依据 SEPG 工作规范 规定。此外，如遇下列条件可进行评审，并根据评审结果决定是否需要进行修订： 本文档所列的引用的标准已经更新。 本文档的使用者若对本文档有任何评论、建议或意见，请通过企业内部网 络发电子邮件给 SEPG，所收到的电子邮件将会在评审和修订时给予充分 的考虑。 精选资料 可修改编辑 使用使用对对象象 本文档的使用对象包括： 项目管理者 质量保证人员 软件开发人员 精选资料 可修改编辑 目目 录录 1介介绍绍 7 1.1为什么要有编码规范 7 2通用代通用代码码格式格式 7 2.1文件组织 7 2.2缩进 8 2.3行长度 8 2.4换行 8 2.5空行 10 2.6空格 10 2.7注释 11 2.7.1注释约定11 2.7.2实现注释的格式12 2.7.3文档注释13 2.7.4快速浏览 javadoc.13 2.8声明 14 2.8.1每行声明变量的数量14 2.8.2初始化14 2.8.3布局15 2.8.4类和接口的声明15 2.9语句 16 2.9.1简单语句16 2.9.2复合语句16 2.9.3返回语句16 2.9.4if，if-else，if else-if else语句16 2.9.5for语句.17 2.9.6while语句.17 2.9.7do-while语句.17 2.9.8switch语句.17 2.9.9try-catch语句.18 2.10SQL.18 3命名命名规规范范 19 3.1总则 19 3.2项目命名 19 3.3命名规则 20 3.4变量命名机制 20 3.4.1基本类型变量命名规则：变量类型标识+逻辑名20 3.4.2一般常用对象命名规则21 3.4.3临时变量命名规则22 3.4.4全局变量、成员变量、局部变量命名规则.22 精选资料 可修改编辑 3.4.5常量命名机制22 3.5HTML 元素变量命名机制 22 3.6JSP 文件命名机制22 4类类、接口、包和、接口、包和编译单编译单元的元的标标准准.23 4.1类的标准 23 4.1.1命名类23 4.1.2注释类23 4.2接口标准 24 4.2.1命名接口24 4.2.2注释接口24 4.3包的标准 24 4.3.1命名包24 4.3.2注释包25 4.4编译单元标准 25 4.4.1命名编译单元25 4.4.2注释编译单元25 5字段字段标标准准 （字段（字段/属性）属性） 26 5.1字段可见性 26 5.2注释一个字段 26 5.3使用存取成员方法 27 5.3.1存取函数的可见性27 5.3.2一定要初始化静态字段27 6成成员员函数和方法函数和方法标标准准 28 6.1命名函数和成员方法 28 6.2命名存取成员函数和方法 28 6.3命名构造函数 29 6.4成员函数和方法的可见性 29 6.5成员函数和方法参数标准 30 6.5.1命名参数30 6.5.2注释参数30 6.6注释成员函数和方法 30 7编编程程惯惯例例 32 7.1提供对实例以及类变量的访问控制 32 7.2引用类变量和类方法 32 7.3常量 32 7.4变量赋值 32 8其它其它惯惯例例 33 8.1圆括号 33 8.2返回值 33 8.3条件运算符“?“前的表达式 .33 精选资料 可修改编辑 8.4特殊注释 34 9代代码码范例范例 34 9.1源文件范例 34 10缩缩写写说说明明 35 11参考参考资资料料 36 精选资料 可修改编辑 1 介介绍绍 1.1 为为什么要有什么要有编码规编码规范范 编码规范对于程序员而言尤为重要，有以下几个原因： 一个软件产品的 80%的生命期是在维护。 几乎没有一个软件在它的整个生命期里都是被它的作者来维护的。 使用好的风格提高了软件的可维护性。 如果源代码和软件产品是捆绑给客户的，作为产品的剩余部分，它应该有 好的分包（well-packaged），足够清晰和专业的代码。 2 通用代通用代码码格式格式 2.1文件文件组织组织 一个文件由被空行分割而成的段落以及标识每个段落的可选注释共同组成。 超过 2000 行的程序难以阅读，应该尽量避免。 Java 源文件必须遵循以下规则： 文件头部注释 所有的源文件都应该在开头有一个 C 语言风格的注释，其中列出文件名、 作者、公司、日期、描述、修改说明和版权声明： /* * File: OrderSessionBean.java * Author: wangxie * Version: 1.1 * Date: 06/04/2004 * Modify: 精选资料 可修改编辑 * Description: * Copyright notice */ 包和引入语句 在 Java 源文件中，第一个非注释行是 Package 语句。Package 行要在 Import 行之前，Import 中标准的包名要在本地的包名之前，而且按照字母顺序 排列。例如： package java.awt; import java.awt.peer.CanvasPeer; import java.io.InputStream; import .cuit.TestApplication; 类和接口声明 下表描述了类和接口声明的各个部分以及它们出现的先后次序。 序号 类/接口声明的各部分 注解 1 类/接口文档注释 (/*/) 该注释中所需包含的信息。 2类或接口的声明 3 类/接口实现的注释 (/*/)如果有必要 的话 该注释应包含任何有关整个类或接口的信息，而这些信息又不 适合作为类/接口文档注释。 4类的(静态)变量 首先是类的公共变量，随后是保护变量，再后是包一级别的变量 (没有访问修饰符，access modifier)，最后是私有变量。 5实例变量 首先是公共级别的，随后是保护级别的，再后是包一级别的(没 有访问修饰符)，最后是私有级别的。 6构造器 7方法 这些方法应该按功能，而非作用域或访问权限，分组。例如，一 个私有的类方法可以置于两个公有的实例方法之间。其目的是 为了更便于阅读和理解代码。 2.2缩进缩进 4 个空格常被作为缩进排版的一个单位，以表示缩进，显示程序的层次级别， 增加程序的可读性。不要在源代码中保留 tab 字符，这是因为 tab 字符会随着不同 精选资料 可修改编辑 用户的不同设置和不同的资源管理工具（打印、文档、版本控制等）而代表不同的 宽度。 2.3行行长长度度 尽量避免一行的长度超过 80 个字符，因为很多终端和工具不能很好处理之。 注意：用于文档中的例子应该使用更短的行长，长度一般不超过 70 个字符。 2.4换换行行 当一个表达式无法容纳在一行内时，可以依据如下一般规则断开之： 在一个逗号后面断开 在一个操作符前面断开 宁可选择较高级别(higher-level)的断开，而非较低级别(lower-level)的 断开 新的一行应该与上一行同一级别表达式的开头处对齐 如果以上规则导致你的代码混乱或者使你的代码都堆挤在右边，那就 代之以缩进 8 个空格。 以下是断开方法调用的一些例子： someMethod(longExpression1, longExpression2, longExpression3, longExpression4, longExpression5); var = someMethod1(longExpression1, someMethod2(longExpression2, longExpression3); 以下是两个断开算术表达式的例子。前者更好，因为断开处位于括号表达 式的外边，这是个较高级别的断开。 longName1 = longName2 * (longName3 + longName4 - longName5) + 4 * longname6; /PREFFER longName1 = longName2 * (longName3 + longName4 精选资料 可修改编辑 - longName5) + 4 * longname6; /AVOID 以下是两个缩进方法声明的例子。前者是常规情形。后者若使用常规的缩 进方式将会使第二行和第三行移得很靠右，所以代之以缩进 8 个空格 /CONVENTIONAL INDENTATION someMethod(int anArg, Object anotherArg, String yetAnotherArg, Object andStillAnother) . /INDENT 8 SPACES TO AVOID VERY DEEP INDENTS private static synchronized horkingLongMethodName(int anArg, Object anotherArg, String yetAnotherArg, Object andStillAnother) . if 语句的换行通常使用 8 个空格的规则，因为常规缩进(4 个空格)会使语句体 看起来比较费劲。比如： /不要使用如下缩进 if (condition1 /易使这行被忽视 /使用如下缩进 if (condition1 /或者使用如下缩进 if (condition1 这里有三种可行的方法用于处理三元运算表达式： alpha = (aLongBooleanExpression) ? beta : gamma; alpha = (aLongBooleanExpression) ? beta : gamma; alpha = (aLongBooleanExpression) ? beta : gamma; 2.5空行空行 空行将逻辑相关的代码段分隔开，以提高可读性。下列情况应该总是使用两 个空行： 一个源文件的两个片段(section)之间 类声明和接口声明之间 下列情况应该总是使用一个空行： 两个方法之间 方法内的局部变量和方法的第一条语句之间 块注释或单行注释之前 一个方法内的两个逻辑段之间，用以提高可读性 2.6空格空格 下列情况应该使用空格： 一个紧跟着括号的关键字应该被空格分开，例如： while (true) . 精选资料 可修改编辑 注意：空格不应该置于方法名与其左括号之间。这将有助于区分关键字和方法调用。 空白应该位于参数列表中逗号的后面 所有的二元运算符，除了“.“，应该使用空格将之与操作数分开。一元操作符和 操作数之间不因该加空格，比如：负号(“-“)、自增(“+“)和自减(“-“)。例如： a += c + d; a = (a + b) / (c * d); while (d+ = s+) n+; printSize(“size is “ + foo + “n“); for 语句中的表达式应该被空格分开，例如： for (expr1; expr2; expr3) 强制转型后应该跟一个空格，例如： myMethod(byte) aNum, (Object) x); myMethod(int) (cp + 5), (int) (i + 3) + 1); 2.7注注释释 Java 程序有两类注释：实现注释(implementation comments)和文档注释 (document comments)。实现注释是那些在 C+中见过的，使用/*.*/和/界定的注释。 文档注释(被称为“doc comments“)是 Java 独有的，并由/*.*/界定。文档注释可以 通过 javadoc 工具转换成 HTML 文件。 注意：注意：频频繁的注繁的注释释有有时时反映出代反映出代码码的低的低质质量。当你量。当你觉觉得被迫要加注得被迫要加注释释的的时时候，考候，考虑虑 一下重写代一下重写代码码使其更清晰。使其更清晰。 2.7.1注注释约释约定定 注注释应该释应该增加代增加代码码的清晰度。的清晰度。代码注释的目的是要使代码更易于被同时 参与程序设计的开发人员以及其他后继开发人员理解。 精选资料 可修改编辑 避免使用装避免使用装饰饰性内容，也就是性内容，也就是说说，不要使用象广告横幅那，不要使用象广告横幅那样样的注的注释语释语句。句。 典型的是用星号将他们的内部注释圈起来。这只是在大量浪费时间，并 不能给最终的产品增加丝毫价值。 保持注保持注释释的的简洁简洁。 。最好的注释应该是简单明了的注释。注释不必洋洋洒 洒，只需提供足够的信息，使别人能够理解你的代码。 先写注先写注释释，后写代，后写代码码。 。写代码注释的最好方法是在写代码之前就写注释。 这使你在写代码之前可以想想代码的功能和运行。而且这样确保不会遗 漏注释。另一种方法是边写代码边写注释。因为注释可以使代码更易理 解，所以在程序开发的过程中，也可以利用这一点。如果打算花些时间 写注释，那么至少你应从这个过程中获得些什么 。 注注释释信息不信息不仅仅要包括代要包括代码码的功能，的功能，还应给还应给出原因。出原因。例如，下面例子中的 代码显示金额在 $1,000 以上（包括 $1,000）的定单可给予 5% 的折扣。为 什么要这样做呢？难道有一个商业法则规定大额定单可以得到折扣吗？ 这种给大额定单的特殊是有时限的呢，还是一直都这样？最初的程序设 计者是否只是由于慷慨大度才这样做呢？除非它们在某个地方（或者是 在源代码本身，或者是在一个外部文档里）被注释出来，否则你不可能知 道这些。 例： if (grandTotal = 1000.00) grandTotal = grandTotal * 0.95; 2.7.2实现实现注注释释的格式的格式 程序可以有 4 种实现注释的风格：块(block)、单行(single-line)、尾端(trailing)和 行末(end-of-line)。 块注释 块注释通常用于提供对文件，方法，数据结构和算法的描述。块注释 被置于每个文件的开始处以及每个方法之前。它们也可以被用于其他地 方，比如方法内部。在功能和方法内部的块注释应该和它们所描述的代码 具有一样的缩进格式。块注释之首应该有一个空行，用于把块注释和代码 分割开来，比如： /* * Here is a block comment. */ 精选资料 可修改编辑 块注释可以以/*-开头，这样 indent(1)就可以将之识别为一个代码块 的开始，而不会重排它。 /*- * Here is a block comment with some very special * formatting that I want indent(1) to ignore. * * one * two * three */ 单行注释 短注释可以显示在一行内，并与其后的代码具有一样的缩进层级。如 果一个注释不能在一行内写完，就该采用块注释(参见“块注释“)。单行注 释之前应该有一个空行。以下是一个 Java 代码中单行注释的例子： if (condition) /* Handle the condition. */ . 尾端注释 极短的注释可以与它们所要描述的代码位于同一行，但是应该有足 够的空白来分开代码和注释。若有多个短注释出现于大段代码中，它们应 该具有相同的缩进。以下是一个 Java 代码中尾端注释的例子： 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. / . / /else / return false; / 2.7.3文档注文档注释释 文档注释描述 Java 的类、接口、构造器，方法，以及字段(field)。每个文档注释 都会被置于注释定界符/*.*/之中，一个注释对应一个类、接口或成员。该注释应 位于声明之前： /* * The Example class provides . */ public class Example . 注意顶层(top-level)的类和接口是不缩进的，而其成员是缩进的。描述类和接 口的文档注释的第一行(/*)不需缩进；随后的文档注释每行都缩进 1 格(使星号纵 向对齐)。成员，包括构造函数在内，其文档注释的第一行缩进 4 格，随后每行都缩 进 5 格。 若你想给出有关类、接口、变量或方法的信息，而这些信息又不适合写在文档 中，则可使用实现块注释或紧跟在声明后面的单行注释。例如，有关一个类实现的 细节，应放入紧跟在类声明后面的实现块注释中，而不是放在文档注释中。 精选资料 可修改编辑 文档注释不能放在一个方法或构造器的定义块中，因为 Java 会将位于文档注释之 后的第一个声明与其相关联。 2.7.4快速快速浏览浏览 javadoc javadoc 的程序可以处理 Java 的源代码文件，并且为 Java 程序产生 HTML 文 件形式的外部注释文档。Javadoc 支持一定数目的标记，标识注释文档中各段起始 位置的保留字。详情请参考 J2SDK javadoc 文档。 标记标记 用于用于目的目的 author name类、 接口 说明特定某一段程序代码的作者。每一个作 者各有一个标记。 deprecated类、 成员函数 说明该类的应用程序编程接口 (API) 已被废 弃，因此应不再使用。 exception name description成员函数说明由成员函数发出的异常。一个异常采用 一个标记，并要给出异常的完整类名。 param name description成员函数用来说明传递给一个成员函数的参数，其中 包括参数的类型/类和用法。每个参数各有一 个标记。 return description成员函数若成员函数有返回值，对该返回值进行说明。 应说明返回值的类型/类和可能的用途。 since类、成员函数说明自从有 JDK 1.1 以来，该项已存在了多 长时间。 see ClassName类、接口、成员 函数、字段 在文档中生成指向特定类的超文本链接。可 以并且应该采用完全合法的类名。 see ClassName#member functionName 类、接口、成员 函数、字段 在文档中生成指向特定成员函数的超文本链 接。可以并且应该采用完全合法的类名。 version text类、接口说明特定一段代码的版本信息。 2.8 声明声明 2.8.1每行声明每行声明变变量的数量量的数量 推荐一行一个声明，因为这样以利于写注释。亦即， 精选资料 可修改编辑 int level; / indentation level int size; / size of table 要优于， int level, size; 不要将不同类型变量的声明放在同一行，例如： int foo, fooarray; /避免！ 注意：上面的例子中，在类型和标识符之间放了一个空格 2.8.2初始化初始化 在声明局部变量的同时初始化。唯一不这么做的理由是变量的初始值依 赖于某些先前发生的计算。 2.8.3布局布局 只在代码块的开始处声明变量。（一个块是指任何被包含在一对大括号 “和“中间的代码。）不要在首次用到该变量时才声明之。这会把注意力不 集中的程序员搞糊涂，同时会妨碍代码在该作用域内的可移植性。 void myMethod() int int1 = 0; / 在方法的开始处 if (condition) int int2 = 0; /在”if ”块的开始处 . 该规则的一个例外是 for 循环的索引变量 for (int i = 0; i = 0) ? x : -x; 8.4特殊注特殊注释释 在注释中使用 XXX 来标识某些未实现(bogus)的但可以工作(works)的内容。 用 FIXME 来标识某些假的和错误的内容。 9 代代码码范例范例 9.1 源文件范例源文件范例 下面的例子，展示了如何合理布局一个包含单一公共类的 Java 源程序。接口的布 局与其相似。更多信息参见“类和接口声明“以及“文挡注释“。 /* * (#)Blah.java 1.82 99/03/18 * * Copyright (c) 1994-1999 Sun Microsystems, Inc. * 901 San Antonio Road, Palo Alto, California, 94303, U.S.A. 精选资料 可修改编辑 * All rights reserved. * * This software is the confidential and proprietary information of Sun * Microsystems, Inc. (“Confidential Information“). You shall not * disclose such Confidential Information and shall use it only in * accordance with the terms of the license agreement you entered into * with Sun. */ package java.blah; import java.blah.blahdy.BlahBlah; /* * Class description goes here. * * version 1.82 18 Mar 1999 * author Firstname Lastname */ public class