Java编码规范(中文版).doc

JAVA 编码规范1. 一 般 规 则 编写能够良好执行的软件是重要的，很多其它因素也让职业的Java程序开发者所关切。所有好的软件都能良好的执行。但是一个优秀的软件，应该是用可预见的，鲁棒的，可维护的，可支持的，可扩展的风格来编写。 1、坚持原有的风格 当我们修改已有软件时，你的改动应该遵循原有的编码风格。不要在修改中引入一种新的编码风格，并且不要试图仅仅为了适应新的风格而去重写原有的软件。在一个源文件中使用两种不同的风格所产生的代码是很难阅读和理解的。仅仅为改变风格而去重写原有代码，将会导致代价昂贵的，却是可避免的错误的引入。 2、坚持最小惊讶原则 最小惊讶原则建议你应该避免做让你的软件用户感到惊讶的事情。这意味着你的软件所展示的交互和行为，应该是可预测的和前后一致的。如果不是这样，那么你的文档一定要清晰地标识，并且证明每一个独特的使用模式或行为模式是合理的。 为了使用户在使用你的软件时遇到的意外最少，你应该在你的Java程序的设计、实现以及文档中强调以下几个特性：(page 1) 简单性 构建简单类和简单方法。决定你需要做多少工作，就能满足用户的需要。 清晰性 确保每一个类、接口、方法、变量和对象都有明确的目的。阐明在什么地方，什么时候，为什么以及怎样使用它们。完整性 提供每一个合理用户可能希望的最小功能。创建完整的文档来记录所有的特征和功能。一致性 相似的实体在外观和行为上应该是相同的；不同的实体在外观和行为上应该是不同的。无论何时，只要可能就要创建并应用这些标准。 鲁棒性 提供可预见的记录行为来响应错误和异常.不要隐瞒错误，更不要迫使用户来发现错误。 3、坚持在第一时间把它做好 把这些规则应用到你所编写的任何代码中，而不仅仅是产品级的代码。经常会有一段原型的或实验的代码进入你最终的产品，所以你要能预见这种事是可能发生的。即使你的代码不会成为产品，其他人仍可能去读它。任何看到你的代码的人，都会因为你能够从一开始就始终如一地应用这些规则而欣赏你的专业水平和远见。(page 2) 4、记录任何与编码规范相违背的地方 没有完美的标准，也没有普遍应用的标准。有时你会发现你会处在不得不违背规范的处境中。 在你决定忽略一个规则之前，你应该首先确信你是知道这个规则为什么存在的，知道如果不应用这个规则会有什么样的后果。如果你决定你必须违背一个规则，那么你要记录你必须这么做的原因。(page 3) （柳学铮译）2 格 式 编 排 的 约 定5缩进嵌套代码增强代码可读性的一种方法是将独立的语句分组为块语句，并且统一缩进每块程序的内容，用以从环境代码中分离其内容。如果你用Java的开发环境开发代码，那么就用开发环境中产生的缩进风格编写。如果你用手工编写代码，则用2个空格来确保程序的可读性，并且这并没有占多大空间：class MyClass void function (int arg) if (arg 0) for (int index = 0; index = arg; index+) /除了要缩进块语句的内容，你还应该缩进后面加了标记的语句，使标记更容易被注意到：void function (int arg) loop:for (int index = 0; index = arg; index+) switch (index) (page 5)case 0;/break loop; / exit the for statementdefault;/break; / exit the switch statement将每块程序开始的括号“”设置在引入程序块的那一行语句的最后一个字符的位置上。将每个程序块的结束括号“”单独放在一行，同引入程序块语句的那一行的第一个字符排成一列。下面的例子说明了这个规则是怎样应用于各种各样的Java定义和控制结构。Class definitions: public class MyClass Inner class definitions: public class OuterClass class InnerClass Method definitions: void method (int j) Static blocks: static (page 6)For-loop statements: for (int i = 0; i = j; i+) If and else statements: if (j 0) else Try,catch,and finally blocks:try catch (Exception e) finally Switch statements: switch (value) case 0:break;default:break;Anonymous inner classes: button.addActionListener ( new ActionEventListener() (page 7) public void actionPerformed () )While statements: while (+k = j) Do-while statements: do while (+k 0.0 ? (x / length) : x;使用空行分隔：在方法实现的每个逻辑区使用空行： void handleMessage(Message message) DataInput content = message.getDataInput();int messageType = content.readInt();switch (messageType) case WARNING: do some stuff here break; case ERROR: do some stuff here break; default: do some stuff here break; 在类或接口中的成员定义的地方使用空行：public class Foo /* Defines an inner class.*/class InnerFoo (page 12) (田苗苗译)/* The Bar associated with this Foo.*/private Bar bar;/* Construct a Foo with the specified Bar.*/Foo(Bar bar) this.bar = bar; 在源文件中每一个类和接口定义的地方使用空行： /* file description */package pany.xyz;/* interface description */interface FooInterface /* class description */public class Foo implements FooInterface 8不要使用 tab键 许多开发人员使用tab键来缩进和排列源代码，但他们没有意识到tab键的字符在不同的环境中会发生变化。在原始编译环境中浏览时，代码能够呈现出正确的格式编排。但当代码被转移到一个tab键字符有差异的编辑环境中时，将出现无格式编排的和不可读的情况。(page 13) 为了避免这个问题，常用空格代替tab键来缩进和排列源代码。这个操作很简单，可以通过用空格键代替tab键或者通过配置编辑程序来代替tab键的实现。一些编译程序还提供了一个“智能的”缩进功能。但在需要使用tab键时，你要使这个功能无效。你的团队应该设置一个共用的缩进尺寸，使它对所有的Java程序都保持一致。（见概要中规则5）(page 14)3 命 名 的 约 定下面的这些命名约定与Sun公司使用的Jsdk命名规则是一致的。9使用有含义的名字 当命名一个类、变量、方法、或常量时，应使用那些，对最终会阅读你的程序的其他程序员来说有含义的名字。使用有含义的词来生成名字，避免使用单个字符或一般的名字。单个字符或一般的名字看不出名字定义的意图。 在下面的程序中，变量“a”与常量“65”的意图是不明确的。 if (a 65) / What property does a describe? y = 65 a; / What is being calculated here? else y = 0; 使用有含义的名字，程序会更容易理解：if (age RETIREMENT_AGE) yearsToRetirement = RETIREMENT_AGE age; else yearsToRetirement = 0;这个规则的唯一例外与临时变量有关，这些临时变量的上下文提供了足够信息来确定它们的意图。例如，在一个循环中被用做计数器或下标的变量： (page 15) （时兵译） for (int i = 0; i numberofStudents; +i) enrollStudent(i);一些变量的含义和使用场景的频繁出现会足以形成一定的标准。（为获得更多的信息，请参看规则 #28）10使用熟悉的名字命名用对象领域中已存在的术语进行命名。如果你的用户习惯将顾客称为 customers,那我们就用customer为类命名，而不是client。许多软件开发者经常会犯这类错误：他们创造出新的或通用的术语来为概念命名。但此时在目标产业或目标领域里，这个概念已经有令人满意的术语了。11起过长名字的问题一个对象的名字必须能够充分地描绘它要表达的意思。如果一个类，接口，变量或方法有一个过长的名字，那么这个实体可能会表达的意思就太多了。我们首先要考虑的是它的设计或意图，而不是简单的只给这个实体一个只能传递少量意义的名字。一个实体的重构也许会产生新的类、接口、方法或变量。他们会具有更集中、更具有表达意义并且更简单的名字。 (page 16)12加入元音字母如果多个有含义的名字都被简化成相同的缩拼词，那么，这些缩拼词就会减少你代码的可读性并引起歧义。 不要试图通过删除元音字母来缩短名字。如果多个有意义的名字都被简化成相同辅音字母的集合，这样也会减弱你代码的可读性并引起歧义。一般的读者都会理解下面这段程序中名字要表达的意义。 public Message appendSignature(Message message,String signature) 但下面这种简化的形式就很难让人理解了。 public Msg appndSgntr(Msg msg,String sgntr) 如果你删除元音字母仅仅是为了缩短一个很长的名字，那么你就应该考虑一下原来的名字是否贴切。（详见 #11）13将缩拼词里的首字母大写用大写字母作为词的分割符有助于消除名字的歧义性，当一个缩拼词后紧跟另一个缩拼词的时候，这种方法就显得尤为重要了： setDSTOffset() setDstOffset() loadXMLDocument()loadXmlDocument() (page 17)这条规则不适用于： 一个常量名字中的缩拼词，因为这些名字里只包括大写字母。（见规则 #31） static final String XML_DOCUMENT = “text/XML”; 出现在一个方法，变量或参数开头的缩拼词，因为这些名字总要以小写字母开头。(见规则22和25)： private Document xmlDocument;14不要使用那些仅在字母大小写上有区别的名字JAVA编译器能够识别那些仅在字母大小写上有区别的名字，但阅读者可能注意不到这种区别。例如，一个名为theSQLInputStream的变量不能和一个名为thesqlInputStream的变量出现在同一作用域中。如果两个名字出现在同一作用域中，那么，当人们从视觉角度阅读或理解这段代码的时候，每一个变量都会有效地屏蔽另一个。包的命名15用你的组织的网络域名的小写、逆序形式作为包的名字的根修饰符。任何分配给其他组织的包都应该包含本组织的域名，这个名字是以小写字母的逆序形式表示。例如，一个名为ROGUE WAVE SOFTWARE 的公司，它的网址为：.该公司要发布一个叫做sever的包，那么，ROGUE WAVE就应该将该包命名为com.roguewave.server。（page 18）（冯卓楠译） SUN公司对于使用java和javax做为包的名字做了严格的限制。以java命名的包仅可以被Java开发商使用，以提供与标准Java类库一致的实现。SUN公司保留javax的使用，用来命名它自己的Java扩展包。16、使用单一的、小写字母的单词作为每个包的根目录名。一个包名被修饰的部分应由单一的、小写字母的单词组成，这个单词应能清晰地捕捉到这个包的意图和效用。包名由一个有意义的缩写组成。可接受的缩写的范例如Java包中的java.io和。17、当一个包的新版本与原来的版本是二进制兼容的时候，可以使用与原来的版本相同的名字。否则，要用一个新名。这条规则的目的是确保具有相同修饰符的两个Java类是二进制的并且彼此行为上是兼容的。Java执行模块是在运行时把一个类的类成员联编给该类的实现。这意味着除非你遵守这个约定，否则你没有办法确保你的应用程序与建立应用程序时，你已经使用和试验的软件是同一版本。如果你创建一个包的一个新版本，但这个包不是二进制的或行为上兼容的，那么你应该改变包的名字。更名可以用多种方法完成，但是最安全和最容易的方法就是简单的给包名增加一个版本号。并且每次递增该版本号，以此产生一个不兼容的更改：（page 20）com.roguewave.server.v1com.roguewave.server.v2.这个方法的一个缺点是：在一个包的客户端代码，和这个包的具体实现之间的关联，被硬编码进入客户端代码。因此只有修改包的客户端代码才能使其邦定到一个包的新版本。类型的命名18、出现在类或接口名中的每个单词的首字母大写大写提供一种可视化的尾接提示，能够在每个名字中分离出单个的单词。首字母大写提供一种能区分类或接口名和变量名的一种机制。（见 Rule#25）public class PrintStream extends FilterOutputStream public interface ActionListener extends EventListener 类的命名19、使用名词命名类类使用名词定义对象或事务。（page 20）Class CustomerAccount public abstract class KeyAdapter implements KeyListener 20、创建相关属性、静态服务或常量时使用复数形式的类名给创建相关属性、静态服务或常量组的那个类一个名字。这个名字可以与由这个类定义的属性、业务或常量类型进行通信。Java.awt.fond.LineMetrics类是一个类的例子，这个类定义了一个处理一组相关属性的对象。/* * The LineMetrics class gives* access to the metrics needed to layout* characters along a line and to layout of* a set of lines.*/ public class LineMetrics public LineMetrics()public abstract int getNumChars();public abstract float getAscent();public abstract float getDescent();public abstract float getLeading();public abstract float getHeight();java.beans.Beans类是一个类的例子，这个类定义了一组相关的不变的业务。/* * The Beans class provides some* General purpose beans control methods.*/（page 21）public class Beans public static Object instantiate() public static Object getInstanceOf() public static boolean isInstanceOf() public static boolean isDesignTime() public static boolean isGuiAvailable() public static void setDesignTime() public static void setGuiAvailable() 下面的java.sql.Type 定义了一个类，他包含了一组相关的静态变量，所以他的名头是复数形式。/* The Type class defines constants* that are used to identify SQL types.*/public class Types public final static int BIT = -7; public final static int TINYINT = -6;public final static int SMALLINT = 5;public final static int INTEGER = 4;public final static int BIGINT = -5;public final static int FLOAT = 6;public final static int REAL = 7;public final static int DOUBLE = 8;public final static int NUMERIC = 2;public final static int DECIMAL = 3;public final static int CHAR = 1;接口的命名21.命名接口的时候应该用名词或者形容词。一个接口的命名可以陈述一个对象提供的服务,也可以描叙一个对象的功能。陈述一个对象提供的服务的时候，我们一般用名词命名接口：(page 22) （范伟琦译）public interface ActionListener public void actionPerformed(ActionEvent e); 而描述功能时候，我们一般用形容词命名接口。多数用于描述功能的接口名称是由动词加able或ible后缀构成的:public interface Runnable public void run();public interface Accessible public Context getContext();方法的命名22方法的名字可以由一个或几个单词组成。其中第一个单词要小写,而其余则是单词中的第一个字母大写而其他字母小写。大写机制使人们可以用视觉将不同的几个单词进行区分。而将第一个单词的第一个字母小写，为区分方法调用与构造函数调用提供了一种机制。class MyImsge extends Image public MyImage() public void flush() public Image getScaledInstance() （page 23）23当命名方法的时候使用动词。方法和操作一般都是用动词来定义行为。class Account private int balance; public void withdraw(int amount) deposit(-1 * amount); public void deposit(int amount) this.balance += amount; 24遵循JavaBeans中关于为属性存取器方法命名的约定。JavaBeans的说明规范中已经为访问属性的方法建立了标准的命名约定。而这些方法特指那些可以访问JavaBeans中属性的方法。当你在命名方法的时候，无论这个方法在什么类中，也不管这个类是否会被执行成一个Beans，你都应该遵守已经制定好的约定。下面的JavaBeans采用用is开头的方法来显示boolean类型:boolean isValid() return this.isValid;下面的JavaBeans用以get名开头的方法来读取其他类型属性: String getName() return ; 下面的方法可以读取索引属性，使用一个int型的索引参数:（page 24）（李志栋译）String getAlias(int index) return this.aliases(index);JavaBeans用以set开头的方法来写入布尔型或其他类型属性。void setValid(boolean isValid) this.isValid = isValid;void setName(String name) = name;设置索引属性的方法命名中包含了一个int型的索引参数:void setAlias(int index,String alias) this.aliasesindex = alias;JDK严格遵守以上这些协议。一旦你定义了一个Bean类，is/get/set这些操作符必须被显式的声明为Bean的一部分，除非你定义一个BeanInfo类。变量命名25变量名中第一的词的首字母要小写而其随后的每个单词的首字母要大写。变量名中的单词要用大写字母分隔，单词的第一个字母小写是用来区分变量名和类名（参看规则18）例如： class Customer private Address address;(page 25) private Phone daytimePhopne; public Address setAddress(Address address) Address oldAddress = this.address; This.address = address; Return oldAddress; public void setDaytimePhone(Phone daytimePhone); 26 使用名词给变量命名涉及到对象或事物的变量，要使用名词来标识，如：class Customer private Address billingAddress; private Address shipingAddress; private Phone daytimePhone; private Vector openOrders; 27以复数形式来命名集合给对象集合中所涉及的字段和变量命名，它们要符合集合中包含的对象类型的复数形式。这样可以使读你代码的人能区别出此变量的单值和复数值。例如： Customer customers = newCustonerMAX-CUSTOMERS; void addCustomer(int index, Customer customer) this.customersindex = customer; （page 26） Vector orderItems = new Vector( ); Void addOrderItem(OrderItem orderItem) This.orderItems.addElement(orderItem); 28对程序中建立的临时变量使用标准命名你应该给大多数变量起具有描述性的名字，但是在Java代码中有许多频繁出现的变量类型都有普通的“速记”名字，你应该选择使用这些名字。下面列举了一些例子： Character c , d , e Coordinate x , y ,z Exception e Graphics g Object o Stream in , out , inOut String s域 名29使用this关键字限制域变量以此来区别其他本地变量为了更简单的区别本地变量和域变量，使用this关键字来限制域变量。如： public class AtomicAdder private int count; public AtomicAdder(int count) this.count = count; （page 27）（唐彬译） public synchronized int fetchAndAdd(int value) int temp = this.count; this.count += value; return temp;public synchronized int addAndFetch(int value) return this.count += value;参数命名30、当一个构造函数或“set”方法分配一个参数给一个域的时候，则给该参数和这个域相同的名字。虽然用局部变量名屏蔽变量实例名是拙劣的风格，但从另一方面说，它还是会存在一些好处的。使用相同的名字能使你解除要提出一个不同名字的负担。使用相同的名字也会为读者提供参数值被指定分配给相同名字的域的一个微妙暗示。class Dude private String name; public Dude(String name) = name; public setName(String name) = name; （page 28）常量命名31、使用大写字母为常量命名并且使用一个下划线来分隔每对单词常量命名的大写机制能把它们和其他的final变量区分开来： class Byte public static final byte MAX_VALUE = 255; public static final byte MIN_VALUE = 0; public static final Class TYPE = Byte.class; （page 29）4、 文 档 的 约 定32、为那些一定会使用和维护你的代码的人编写文档记录你的代码的公共编程接口，以便其他人可以正确地和高效地使用它。记录你的代码的私有接口和内部实现细节 以便其他人可以维护和增强它。总是假定完全不熟悉你的代码的人，最终将不得不去阅读和理解它。实际上，如果时间过得足够长，你对自己的代码或许也会变得陌生。所以这个完全不熟悉你的代码的人甚至或许就是你自己！33、保持注释和代码的同步当代码和注释不一致时，二者或许都是错的 Norm Schryer，Bell Labs当你修改代码时，确保你同时更新了任何与之相关的注释。代码和注释一同构成一个软件产品，所以要以同等的重要程度对待它们之中的每一个。34、使用主动语态来省略无用的词注释是一种平白的文本。对于技术性的文档强有力的、清晰的和简洁的语言是特别有益处的。使用它！(page 31) (胥旭译)注释类型Java支持三种注释类型： 文档注释类型以“/*”开头，以“*/”结尾：/* * A documentation comment. */ 标准的，C类型的注释，“/*”开头，以“*/”结尾: /* * A standard comment. */ 单行注释或行尾注释，以“/”开始，直至行尾结束:/ A one-line comment. class MyClass int myFrield;/ An end-line comment. 每一种注释类型服务于一种特定的用途，你可以根据用途来选用一种合理的注释类型。35使用注释文档来描述程序设计的接口你可以在代码中出现的任何类、接口、方法、构造函数或域的前面,放置文档注释。这些注释为产生HTML类参考或API文档提供Javadoc实用工具的使用方法。为了创建文档，Javadoc实用工具在，分析出现在java源代码文件中的全部的声明时，读这些注释。Javadoc利用这些信息去默认的生成源文件中出现的所有公用类、保护类、内部类、接口、构造函数、方法和域所描绘的相应的HTML网页。（page 32）Javadoc仅仅识别在类、接口、构造函数、方法或域声明前面紧接着出现的文档注释。Javadoc不识别任何出现在方法体内的文档注释，所以不要以这种方式使用文档注释。Javadoc允许每个声明语句处有唯一的文档注释，所以，不要尝试在每个声明处使用超过一个的注释字块。注释文档最主要的目的是为客户和服务器供应者制定程序契约，与方法相关的注释将描述这个方法的调用者所依赖的行为的所有方面，但是不尝试描述实现的细节。下面代码说明了声明内部类、域、方法和构造函数的文档注释的使用。 /* * The Rectangle2D class describes* a rectangle defined by location (x,y) and* dimensions (w,h).* */public abstract class Rectangle2D extends RectangularShape /* * The Double class defines a* rectangle specified in double coordinates*/static class Double extends Rectangle2D (page 33)/* The bitmask that indicates that a point lies* below this Rectangle2D */ static int OUT_BOTTOM; /* * Adds a Rectangle2D to this Rectangle2D */ public void add(rectangle2D r) /* * This is an abstract class that cannot be * instantiated directly */protected Rectangle2D() 36在不移除代码的前提下，使用标准注释屏蔽代码当你不想在源文件中真正的移除代码，而是要在编译器中暂时的屏蔽代码时，可以使用这种标准C类型的注释。你仅仅可以在，当没有其他注释块嵌入在内部的代码中时，使用这种注释来“注释掉”一部分代码。 因为C类型注释看上去和文档注释很相象，所以，为了避免由注释块嵌套产生问题，那么，你若不是想暂时的屏蔽代码，就不要使用这种类型的注释。下面的代码片段演示了如何使用这种注释类型来屏蔽成员函数的定义。/* * deprecated*/ (page 34)（姜秋艳译）/* I have temporarily removed this method because it has been deprecated for some time,and I want to determine whether any other packages are still using it! J.Kirk on 9 Dec 1937public void thisOldFunction() /There has got to be a better way! */37. 使用单行注释来阐明实现的细节使用单行或多个单行的注释来记录： 特殊变量或表达式的用途 实现级的设计决策 复杂算法的原始资料 修正缺点或变通法则 代码应受益于更加优化和细化 已知的问题，局限，或缺限通过书写代码来记录自身，从而尽可能的使内嵌注释的需求最小化。不要通过添加注释来简单地重述代码所做的事情，相反，仅仅当能为代码增加有用的信息时，再去添加注释。 Double totalCost;/ Used to total invoice./ Apply the discount to all invoices over $1000.If (totalCost 1000.0) / :TODO: Use constant?/ The discount is hard-coded because current/ customers all use the same discount rate.(page 35)/ We will need to replace this constant with a/ variable if we ever get a customer who needs/ a different rate,or one that wants to app