JAVA源代码规范

.JAVAJAVA 代码规范代码规范(初稿)2004.4. 版本更新信息版本更新信息本版本创建/修改、维护、批准涉及人员如下：创建/修改者：XX维护者：XX批准者：XX具体版本更新记录如表 1-1：表表 1-11-1 版本更新记录版本更新记录版本号 修改确认日期修改人修改位置 修改方式（AMD）修改内容概述V1.02004.4 XX全部A初始版本发布修改方式：修改方式：A增加增加 M修改修改 D删删除除. 目的目的本文提供一整套编写高效可靠的 Java 代码的标准、约定和指南。它们以安全可靠的软件工程原则为基础，使代码易于理解、维护和增强灵活性。通过遵循一套通用的程序设计标准，显著提高 Java 软件开发者的生产效率，为开发团队的程序设计带来更大的一致性，使软件开发团队的效率明显提高。 规范的执行规范的执行本文档适用于公司内进行软件开发的所有技术人员，即公司内软件开发人员编写的所有源代码都必须遵循本规范。除临时性项目之外的任何项目均应严格按照此标准执行， “临时性项目”指： 为市场推广目的而编写的示程序 为一次性用途而编写的临时性小程序为学习目的而编写的测试程序 文档类别文档类别本文档属标准规范类的项目限制级文档，未经总经理及总经理授权人员批准，不得提供公司以外的人员阅读和使用。 版本更新条件版本更新条件本文档的定期评审时间为每年的 1 月，评审及修订步骤依据 SEPG 工作规范规定。此外，如遇下列条件可进行评审，并根据评审结果决定是否需要进行修订：本文档所列的引用的标准已经更新。本文档的使用者若对本文档有任何评论、建议或意见，请通过企业内部网络发电子邮件给 SEPG，所收到的电子邮件将会在评审和修订时给予充分的考虑。 使用对象使用对象本文档的使用对象包括：项目管理者质量保证人员软件开发人员.目目 录录1介绍介绍 .71.1为什么要有编码规范 .72通用代码格式通用代码格式 .72.1文件组织 .72.2缩进 .82.3行长度 .82.4换行 .82.5空行 .102.6空格 .102.7注释 .112.7.1注释约定.112.7.2实现注释的格式.122.7.3文档注释.132.7.4快速浏览 javadoc.132.8声明 .142.8.1每行声明变量的数量.142.8.2初始化.142.8.3布局.152.8.4类和接口的声明.152.9语句 .162.9.1简单语句.162.9.2复合语句.162.9.3返回语句.162.9.4if，if-else，if else-if else语句.162.9.5for语句.172.9.6while语句.172.9.7do-while语句.172.9.8switch语句.172.9.9try-catch语句.182.10SQL.183命名规范命名规范 .193.1总则 .193.2项目命名 .193.3命名规则 .203.4变量命名机制 .203.4.1基本类型变量命名规则：变量类型标识+逻辑名.203.4.2一般常用对象命名规则.213.4.3临时变量命名规则.223.4.4全局变量、成员变量、局部变量命名规则.22.3.4.5常量命名机制.223.5HTML 元素变量命名机制 .223.6JSP 文件命名机制.224类、接口、包和编译单元的标准类、接口、包和编译单元的标准 .234.1类的标准 .234.1.1命名类.234.1.2注释类.234.2接口标准 .244.2.1命名接口.244.2.2注释接口.244.3包的标准 .244.3.1命名包.244.3.2注释包.254.4编译单元标准 .254.4.1命名编译单元.254.4.2注释编译单元.255字段标准字段标准 （字段（字段/属性）属性）.265.1字段可见性 .265.2注释一个字段 .265.3使用存取成员方法 .275.3.1存取函数的可见性.275.3.2一定要初始化静态字段.276成员函数和方法标准成员函数和方法标准 .286.1命名函数和成员方法 .286.2命名存取成员函数和方法 .286.3命名构造函数 .296.4成员函数和方法的可见性 .296.5成员函数和方法参数标准 .306.5.1命名参数.306.5.2注释参数.306.6注释成员函数和方法 .307编程惯例编程惯例 .327.1提供对实例以及类变量的访问控制 .327.2引用类变量和类方法 .327.3常量 .327.4变量赋值 .328其它惯例其它惯例 .338.1圆括号 .338.2返回值 .338.3条件运算符?前的表达式 .33.8.4特殊注释 .349代码范例代码范例 .349.1源文件范例 .3410缩写说明缩写说明 .3511参考资料参考资料 .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 cn.edu.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 & condition2) | (condition3 & condition4) |!(condition5 & condition6) /不好的换行 doSomethingAboutIt(); /易使这行被忽视 /使用如下缩进 if (condition1 & condition2) | (condition3 & condition4) |!(condition5 & condition6) doSomethingAboutIt(); . /或者使用如下缩进 if (condition1 & condition2) | (condition3 & condition4) |!(condition5 & condition6) doSomethingAboutIt(); 这里有三种可行的方法用于处理三元运算表达式： 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快速浏览快速浏览 javadocjavadoc 的程序可以处理 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 maxLoops; i+) . 避免声明的局部变量覆盖上一级声明的变量。例如，不要在内部代码块中声明相同的变量名： int count; . myMethod() if (condition) int count = 0; / 避免！ . . 2.8.4类和接口的声明类和接口的声明当编写类和接口时，应该遵守以下格式规则：在方法名与其参数列表之前的左括号(间不要有空格。左大括号位于声明语句同行的末尾。右大括号另起一行，与相应的声明语句对齐，除非是一个空语句，应紧跟在之后 。 class Sample extends Object int ivar1; int ivar2; Sample(int i, int j) ivar1 = i; ivar2 = j; . int emptyMethod() . 2.9语句语句2.9.1简单语句简单语句每行至多包含一条语句，例如： argv+; / 正确 argc-; /正确 argv+; argc-; / 避免！ 2.9.2复合语句复合语句复合语句是包含在大括号中的语句序列，形如 语句 。例如下面各段。大括号中的语句应该较之复合语句缩进一个层次。左大括号应位于复合语句起始行的行尾；右大括号应另起一行并与复合语句首行对齐。大括号可以被用于所有语句，包括单个语句，只要这些语句是诸如if-else 或 for 控制结构的一部分。这样便于添加语句而无需担心由于忘了加括号而引入 bug。 2.9.3返回语句返回语句一个带返回值的 return 语句不使用小括号()，除非它们以某种方式使返回值更为显见。例如： return; return myDisk.size(); return (size ? size : defaultSize); 2.9.4if，if-else，if else-if else 语句语句if-else 语句应该具有如下格式： if (condition) statements; if (condition) statements; else statements; if (condition) statements; else if (condition) statements;. else statements; 注意：if 语句总是用和括起来，避免使用如下容易引起错误的格式： if (condition) /避免！省略 ! statement; 2.9.5for 语句语句一个 for 语句应该具有如下格式： for (initialization; condition; update) statements; 一个空的 for 语句(所有工作都在初始化，条件判断，更新子句中完成）应该具有如下格式： for (initialization; condition; update); 当在 for 语句的初始化或更新子句中使用逗号时，避免因使用三个以上变量，而导致复杂度提高。若需要，可以在 for 循环之前(为初始化子句)或 for循环末尾(为更新子句)使用单独的语句。2.9.6while 语句语句一个 while 语句应该具有如下格式 while (condition) statements; 一个空的 while 语句应该具有如下格式： while (condition); 2.9.7do-while 语句语句一个 do-while 语句应该具有如下格式： do statements; while (condition); 2.9.8switch 语句语句一个 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 是冗余的，但可预防以后增加另一个选项后没有中断执行导致错误的情况出现。2.9.9try-catch 语句语句一个 try-catch 语句应该具有如下格式： try statements; catch (ExceptionClass e) statements; 一个 try-catch 语句后面也可能跟着一个 finally 语句，不论 try 代码块是否顺利执行完，它都会被执行。 try statements; catch (ExceptionClass e) statements; finally statements; 2.10 SQLSQL 语句中所有的关键字大写，主语句太长需换行时，要求缩进四个空格。子语句提行书写并缩 进一个四个空格。当 where 后带有两个以上的条件时，条件需换行书写，如有逻辑符号则应写在每个条件语句的前面。例如：SELECT 字段 1，字段 2，字段 3，Count(*) FROM 表 1，表 2 WHERE 条件 1 AND 条件 2 OR 条件 3 GROUP BY 字段 1，字段 2，字段 3. ORDER BY 字段 1，字段 2，DESC 字段 33 命名规范命名规范3.1总则总则凡在精联公司内进行开发的任何软件项目的命名，无论是项目名称、文件名、数据库名、表名、 字段名、SQL 存贮过程名、变量名、函数名、类名、组件名，均应符合以下规定：名称全部由下划线、英文字母和数字组成在以下情况下可以在名称中出现数字：用于命名版本(项目版本、文件版本、函数版本等)用于临时性的小程序(如演示程序、测试程序、编程学习程序等)的变量命名因特殊原因两个对象(指项目、文件、数据库等)一定要具有相同的英文名称时如果系统限制名称长度(如某些数据库管理系统中表的命名)低于 32 位字符，则以系统限制为标准；否则任何对象(指项目、文件、数据库等)的名称均不得超过 32 个字符(命名文件时扩展名不计)除以下情况外，名称全部应由有意义的英文单词（当英文单词很难表达时，可以变通采用汉字拼音）组成，并且不超过 5 个英文单词Word 文档的命名命名数据库、表、字段名时用到的开头特定字符(mc_) 临时性项目(如演示程序、测试程序、编程学习程序等)3.2项目命名项目命名一般来说，项目名称有两个含义。一是该项目的通用名，如“合理用药系统”，主要用于公司内部交流，它可以是中文也可以是英文，且不受本规范的限制；二是该项目在开发人员进行代码管理时用的英文缩写名，如“PASS” ，它用于项目在计算机上的管理。此处主要讨论后一种命名。项目名称由该项目的负责人指定项目名称用于以下场合：如命名 Visual Source Safe 项目名命名该项目在开发人员本地计算机的工作文件夹名命名 WSAD 的.ear 文件名命名用于保存、拷贝、压缩、电邮传递等场合的文件夹名或文件名一般情况下项目名不应含版本信息，如遇特殊情况，由可考虑用数字和下划线的方式来指定版本。如 PASS_2_0 表示 PASS 2.0 版。规范的项目名称如：规范的项目名称如：项目通用名称：健康信息管理系统项目名称：PIMSVisual Source Safe 项目名：PIMS.该项目各开发人员在本地计算机上的工作文件夹名：PIMSWSAD 项目文件名：PIMS如导出该项目压缩成一个文件可能名称为：PIMS.ear3.3命名规则命名规则命名规范使程序更易读，从而更易于理解。它们也可以提供一些有关标识符功能的信息，以助于理解代码，例如，不论它是一个常量，包，还是类。3.4 变量命名机制变量命名机制3.4.1基本类型变量命名规则：变量类型标识基本类型变量命名规则：变量类型标识+逻辑名逻辑名变量类型标识用于标识该变量所存储的数据类型，小写字母开头。标识符类型命名规则例子包(Packages)一个唯一包名的前缀总是全部小写的 ASCII 字母并且是一个顶级域名，通常是com，edu，gov，mil，net，org，或 1981 年 ISO 3166标准所指定的标识国家的英文双字符代码。包名的后续部分根据不同机构各自内部的命名规范而不尽相同。这类命名规范可能以特定目录名的组成来区分部门(department)，项目(project)，机器(machine)，或注册名(login names)。com.apple.quicktime.v2 edu.cmu.cs.bovik.cheese类(Classes)命名规则：类名是个一名词，采用大小写混合的方式，每个单词的首字母大写。尽量使你的类名简洁而富于描述。使用完整单词，避免缩写词(除非该缩写词被更广泛使用，像 URL，HTML)Class Raster;class ImageSprite;接口(Interfaces)命名规则：大小写规则与类名相似interface RasterDelegate;interface Storing;方法(Methods)方法名是一个动词，采用大小写混合的方式，第一个单词的首字母小写，其后单词的首字母大写。run();runFast();getBackground();变量(Variables)除了变量名外，所有实例，包括类，类常量，均采用大小写混合的方式，第一个单词的首字母小写，其后单词的首字母大写。变量名不应以下划线或美元符号开头，尽管这在语法上是允许的。变量名应简短且富于描述。变量名的选用应该易于记忆，即，能够指出其用途。尽量避免单个字符的变量名，除非是一次性的临时变量。临时变量通常被取名为 i，j，k，m 和 n，它们一般用于整型；c，d，e，它们一般用于字符型。char c;int i;float myWidth;实例变量(Instance Variables)大小写规则和变量名相似，除了前面需要一个下划线int _employeeId;String _name;Customer _customer;常量(Constants)类常量和 ANSI 常量的声明，应该全部大写，单词间用下划线隔开。(尽量避免 ANSI 常量，容易引起错误)static final int MIN_WIDTH = 4;static final int MAX_WIDTH = 999;static final int GET_THE_CPU = 1;.逻辑名为变量所具有的表示具体应用含义的名称，要做到见名知意，书写时要以字母开头，首字母大写基本变量类型标识 定义如下：Type Prefix - short s int i/n char c/ch double dboolean blong lfloat f3.4.2一般常用对象命名规则一般常用对象命名规则以下为一些常用对象前缀。如果有些对象不在以下表格中，请将该对象类名小写做为前缀。 常用对象前缀 如下：Type Prefix Type Prefix Short short Boolean booleanInteger int Long longChar char Float fltObject obj String strDate dt Event eventDemenstion obj Size sizeColor clr Context ctxConnection conn RecordSet rsStatement stmt Command cmdWindow wnd Frame frameDialog dlg File fileButton btnSocket skt Image img InputStream insOutputStream outs PrintStream psRequest request/resq Response response/resp Double dbl例如：int nCount; long lLength; Object objResult; String strUserName; .Frame frameMain; 3.4.3 临时变量命名规则临时变量命名规则一般临时变量没有一个具体的意思，所以一般临时变量名为 Temp 或 Tmp。其中有一些为 C 语言 或 Fortan 延续下来的常见临时变量也可以接受：如 i ，j ，k 一般用于表示一个临时整型变量。如：int nTemp ,IString strTempBoolean bTmp long lTem 3.4.4全局变量、成员变量、局部变量命名规则全局变量、成员变量、局部变量命名规则局部变量：指在一个程序模块中声明使用的变量，该类变量使用 3.3中定义的命名规则(以后称一般命名)。全局变量：一般为多个模块公有，所以在命名区别于局部变量，要在一般命名的变量名前加上前缀：g_如：int g_nUserCount 成员变量：是指类成员变量，用于表示类的一种或一类属性。要在一般命名的变量名前加上前缀：m_ 如： String m_strName3.4.5 常量命名机制常量命名机制在 Java 中常量名一般为大写，单词之间用_分隔。如：public static final int MAX_USER_COUNT = 100 ; 3.5 HTML 元素变量命名机制元素变量命名机制form name：frmFormNamehidden，text：首字母大写，不用下划线。如：ClientID， OrderID，UserName，Passwd，etcbutton，submit：btnButtonName如：3.6 JSP 文件命名机制文件命名机制JSP 文件命名方式：首字母大写,不用下划线。如：OrderSearch.jspClientMng.jsp.4 类、接口、包和编译单元的标准类、接口、包和编译单元的标准4.1类的标准类的标准4.1.1命名类命名类标准 Java 约定是使用完全的英文描述符，所有单词的第一个字母要大写，并且单词中大小写混合。类名应是单数形式。举例：CustomerEmployeeOrderOrderItemFileStreamString4.1.2注释类注释类以下的信息应写在文档注释中紧靠类的定义的前面： 1.类的目的。类的目的。开发者需要了解一个类的一般目的，以判断这个类是否满足他们的需求。养成一个注释与类有关的任何好东西的习惯，例如：它是否是一个模式的一部分，或是使用它时有什么要引起注意的限制。 2.已知的问题。已知的问题。如果一个类有任何突出的问题，应说明出来，让其他的开发者了解这个类的缺点/难点。此外，还应注明为什么不解决问题的原因。注意：如果问题仅仅针对一个成员方法，那么它应直接与那个成员方法相联系。 3.类的开发类的开发/维护历史。维护历史。通常要包含一个历史记录表，列出日期、类的作者和修改概要。这样做的目的是让进行维护的程序员了解过去曾对一个类所做的修改，是谁做了什么样的修改。 4.注释出采用的不变量。注释出采用的不变量。不变量是指一套有关实例或类在所有“稳定”时间片内为“真”的声明。 “稳定时间片”是指在一个成员函数被对象/类调用之前和立刻调用之后的时间。通过说明一个类的不变量，你让其他的开发者了解应该如何使用一个类。 5.并行策略并行策略。任何采用 Runnable 接口的类应充分说明它的并行策略。对许多程序员来说，并行编程是一个新的而且复杂的题目，所以需要投入一些额外的时间来确保人们能够读懂你的东西。说明你的并行策略以及为什么选取这个策略而不是其它策略这很重要。常用的并行策略 包括下面一些内容：同步对象；停滞 (balking) 对象；警戒 (guarded) 对象；版本 (versioned) 对象；同步策略控制器；接收器。.例例: /* * A class representing a window on the screen. * For example: * * Window win = new Window(parent); *win.show(); * * * seeawt.BaseWindow * seeawt.Button * version1.2 2004-4-9 * author wangxie*/class Window extends BaseWindow .4.2接口标准接口标准4.2.1命名接口命名接口在接口名前加前缀在接口名前加前缀“I” 。建议在一个接口名的前面附加上字母“I” ，结果使名字变为如 ISingleton 或 IRunnable 这样。这种方法有助于将接口名与类和包的名字区分开来。4.2.2注释接口注释接口以下的信息应写在文档注释中紧靠接口定义的前面：目的。目的。在其他开发者应用一个接口之前，他们需要理解接口封装的概念。换句话说，他们需要了解接口的目的。一个好的检测是否有必要定义一个接口的方法是你是否可以很容易地说明它的目的。 如果说明起来有困难，很可能从一开始起就不需要这个接口。在 Java 中接口的概念较新，所以人们对如何正确使用它们还不是很有经验，常常滥用它们。 它应如何被使用以及如何不被使用。它应如何被使用以及如何不被使用。开发者需要了解接口应如何使用以及如何不被使用。 因为成员方法的标识在接口中定义，所以对于每个成员方法的标识应遵循 2.7 中的注释约定4.3包的标准包的标准4.3.1命名包命名包关于包的命名有几条规则。按顺序来说，这些规则是： 标识符用点号分隔开来。标识符用点号分隔开来。为了使包的名字更易读，Sun 公司建议包名中的标识符用点号来分隔。例如，包名 java.awt 含有两个标识符 java 和 .awt。 Sun 公司的标准公司的标准 java 分配包用标识符分配包用标识符 .java 开头。开头。Sun 保有这种权利，使得无论你的 Java 开发环境的零售商是怎样的，标准 java 包的命名始终一致。局部包的名字中的第一个标识符不能都是大写。局部包的名字中的第一个标识符不能都是大写。所谓局部包是指那些在你的机构内部使用，不会应用到其他机构中去的包。这样的包的名字的例子有 persistence.mapping.relational 和 interface.screens。 全局包的名字用你的机构的全局包的名字用你的机构的 Internet 保留域名开头。保留域名开头。一个要应用到多个机构的包应包含创建机构的域名，并且最高层的域名类型要大写。4.3.2注释包注释包应保证有一个或者多个外部文档以说明你的机构所创建的包的用途。对于每个包，应说明： 包的基本原理。包的基本原理。其他开发者需要了解一个包是用来做什么的，这样他们才能判断是否可以用它，如果是一个共享包，他们可以判断是否需要改进或是扩展它。 包中的类。包中的类。在包中要包含一个类和接口的列表，每个类或接口用简短的一行文字来说明，以便让其他的开发者了解这个包中含有什么。 4.4编译单元标准编译单元标准4.4.1命名编译单元命名编译单元编译单元，在这个情况下是一个源码文件，应被赋予文件内定义的主要的类或接口的名字。用与包或类相同的名字命名文件，大小写也应相同。扩展名 .java 应作为文件名的后缀。例：例：Customer.javaSingleton.javaSavingsAccount.java4.4.2注释编译单元注释编译单元虽然应努力使一个文件中只包含一个类或接口，但是有时在一个文件中定义数个类（或者接口）也可理解。一般的经验规则是，如果类 B 的唯一用途是封装只被类 A 需要的功能，那么可以理解类 B 出现在与类 A 相同的源码文件中。下面的文档约定应用于一个源码文件，而不具体到类： 对于有几个类的文件，列出每一个类。对于有几个类的文件，列出每一个类。如果一个文件包含多个类，则应给出一个类的列表，并且简要地说明每个类。 文件名和文件名和/或标识信息。或标识信息。文件名应包含在它的顶端。好处是如果代码被打印出来了，你会知道源码文件是什么。 版权信息。版权信息。若可能，应说明文件的所有版权信息。通常的做法是说明版权的年份和版权持有个人/机构的名字。注意：代码的作者可能不是版权持有者。 .5 字段标准字段标准 （字段（字段/属性）属性）5.1字段可见性字段可见性当字段被声明为 protected 类型时，子类中的成员函数可能会直接访问它，增加了类的耦合性。这使类更难维护和加强，所以应该尽量避免。字段不应被直接访问，而应采用存取成员函数（参见下文）访问。可见性可见性说明说明正确用法正确用法public一个公共字段可被任何其他对象或者类中的成员函数访问。尽量不要让字段公有。protected被保护的字段可被它声明时所在的类及该类的子类的所有成员函数访问。尽量不要让字段被保护。private私有字段只可以被它声明时所在的类的其它成员函数调用，该类子类中的函数不可以调用。所有的字段都应尽可能置为私有，由获取和设置成员函数（存取函数）访问。5.2注释一个字段注释一个字段所有的字段都应很好地加以注释，以便其他开发者理解它。要想有效地注释，以下的部分需要说明： 字段的说明。字段的说明。使用 javadoc 来描述字段的用途和约束。在注释中增加如下标签。see stringsee URLsee classname#methodname 注释出所有采用的不变量。注释出所有采用的不变量。字段中的不变量是指永远为“真”的条件。例如，字段 dayOfMonth 的不变量可能是它的值只能在 1 到 31 之间（显然，可以用基于某一年里的某个月份来限制这个字段值，使其变的更加复杂） 。通过说明字段值的限制条件，有助于定义重要的业务规则，使代码更易理解。示例。示例。对于那些有复杂业务规则与之相关联的字段，应提供几个例子，使它们容易理解。一个例子常象一幅画：它抵得上几千个词语。 并行事件。并行事件。对众多程序开发者来说，并行性是一个新而复杂的概念；事实上，即使对有经验的并行程序开发者来说，并行性也是一个老但却复杂的课题。最终结果是，如果应用了 Java 的并行编程特性，那么你应在程序中详细地注释出来。 可见性决策。可见性决策。如果声明了一个非私有字段，则应说明为什么要这样做。.字段的可见性在上文中（第 5.1 节“字段的可见性” ）讨论了，支持封装的存取成员函数的用法将在下文（第 5.3 节“使用存取成员方法” ）中讨论。总的来说，最好能有一个好的理由解释为什么不将变量声明为私有类型。 例: /* * The current number of elements. * must be non-negative, and less than or equal to capacity. */ protected int count_;5.3使用存取成员方法使用存取成员方法除了满足命名约定之外，适当地使用存取成员函数，即提供更新或访问字段值的成员函数，可以实现字段的可维护性。存取成员函数有两种：设置函数（也叫变化函数）和获取函数。设置函数修改变量的值，获取函数取到变量的值。存取成员函数通过以下方法提高类的可维护性： 更新字段。更新字段。.每个字段只有几个单点要更新，这使得修改和检测都很容易。换句话说，字段已被封装。获得字段的值获得字段的值。你完全控制着字段应怎样被访问以及被谁访问。 获取常量名和类名获取常量名和类名。在获取函数中封装常量值和类名，当这些值或名字改变时，只需更新获取函数内的值，而并非常量或者名字被使用处的每一行代码。 初始化字段初始化字段。采用滞后初始化 (lazy initialization) 保证字段总能被初始化，并且只在需要时才初始化。 减少类与子类之间的耦合减少类与子类之间的耦合。 当子类通过它们相应的存取成员函数访问被继承的字段时，它可以不影响它的任何子类，而只修改超类字段的实现方式，这样有效地减少了超类与子类之间的耦合。存取函数减少了那种一旦超类被修改就会波及子类的“脆弱基类”的风险。 将变化封装到字段中将变化封装到字段中。如果一个或者多个字段的业务规则变化了，可以只潜在地修改存取函数，就同样可以提供规则变化之前的功能。这一点使你很容易响应新的业务规则。 简化并行事件。简化并行事件。如果采用了基于字段值的 waits 语句，那么设置成员函数提供了一个位置可包含 notifyAll。这让转向并行解决方案更加容易。 5.3.1存取函数的可见性存取函数的可见性尽可能地让字段成为被保护 (protected) 类型，这样只有子类可以访问它们。仅当一个外部类需要访问一个字段时，才将相应的获取函数或设置函数置为公有。注意：获取函数是公有而设置函数是私有的情况经常发生。5.3.2一定要初始化静态字段一定要初始化静态字段静态字段，也叫类字段，应被赋予有效值，因为不能假定类的实例将在一个静态字段被访问之前生成。.6 成员函数和方法标准成员函数和方法标准6.1命名函数和成员方法命名函数和成员方法成员函数的命名应采用完整的英文描述符，大小写混合使用：所有中间单词的第一个字母大写。成员函数名称的第一个单词常常采用一个有强烈动作色彩的动词。例：例：openAccount()printMailingLabel()save()delete()这种约定常常使人一看到成员函数的名称就能判断它的功能。虽然这种约定要使开发者多做一些输入的工作，因为函数名常常较长，但是回报是提高代码的可理解性。6.2命名存取成员函数和方法命名存取成员函数和方法获取成员函数应在名字中加上 get + 字段名，除非字段表示的是一个布尔值（“真”或者“假” ） ，这时获取函数名中应加上 is + 字段名。无论何种字段类型，设置成员函数应在名字中加上 set + 字段名。注意字段名始终采用大小写混合，所有单词的第一个字母要大写。命名约定在 JDK 中被始终使用，在 beans development 中也必须使用。Examples:字段字段类型类型获取函数名获取函数名设置函数名设置函数名firstName 字符串 getFirstName() setFirstName() address 地址对象 getAddress() setAddress() persistent 布尔值 isPersistent() setPersistent() customerNo 整型 getCustomerNo() setCustomerNo() .orderItems OrderItem的对象数组 getOrderItems() setOrderItems() 6.3命名构造函数命名构造函数构造函数是在一个对象初次生成时，完成所有必需的初始化的成员函数。构造函数与它所属类的名字总是相同的。例如，类 Customer 的构造函数是 Cu