Java编程规范

《Java编程规范》由会员分享，可在线阅读，更多相关《Java编程规范（17页珍藏版）》请在装配图网上搜索。

1、6af94dc9e71adc9cb2457ad8524c54a6.docCreated by JeffJava编程规范嵌入式产品部中科软科技股份限公司作者：Jeff版本1.0草稿完成日期：2002-1-17郑重声明本文中的绝大多数内容都摘自“JavaCodingStandard.pdf”，其中我仅仅做了少量的修改和说明，基本就是抄袭。详细信息请参见原文。说法不对的地方，请及时反馈给Jeff。1. 基础1.1 如何定义一个好的名字l 使用完整的语言来描述变量/属性/类/，不要采用简写。例如变量CustomerName，不要使用CustNm。（如果使用简写，则采用统一的标准）l 采用所涉及的领域中

2、的专用术语，例如针对习惯，将客户都称为Customer，或是Client，不要混合两者使用。l 混合使用大小写，使名称更容易被他人看懂。l 尽量少使用简写，如果使用，则要保证一致性，例如，对于number，可以使用nbr、num或是no，但不管使用哪一个，都要保证编程中的一致性，并将自己的简写规范写入自己的简写文档。l 尽量不要出现超过15个字符的名称。例如对于PhysicalOrVirtualProductOrService，可以用Offering代替。l 避免名称相似或是仅仅在大小写上有区别。1.2 良好的文档l 添加适当的注释，使你的代码能够很容易被人看懂。l 如果你的代码不值得注释，那

3、么这些代码也不值得运行。l 避免使用太多的装饰用注释，例如使用太多的*号来装饰你的注释。l 保持注释的简洁，只要保证能说明你的代码就行，不必象写书一样。l 在编写代码之前编写注释。这种方法一是能保证你写注释，另一个优点是可以帮助你整理思路。l 注释中要能解释为什么这么做，而不仅仅是做了什么。例如对于下面的代码，就需要解释为什么使用魔术数字1000和0.95。if ( grandTotal = 1000.00)grandTotal = grandTotal * 0.95;1.3 Java的注释Java的注释有三种类型注释类型用法例子文档（用于Javadoc）注释紧接在接口、类、成员函数之前的注释

4、，便于javadoc处理，详细信息参见javadoc文档（参见下面提到的题头）/*Customer 客户指的是我们向他销售服务和产品的人或组织author Jeff.Liu*/C类型多用于主要注释多行，这种注释的用途主要表明作者的意图，或是在调试时临时注释/*这段代码是由Jeff.Liu在2002年1月10日注释的，原因是这段代码已被上面的代码替代。如果两年后仍然不需要这些代码，请到时将它删除。. . . (the source code )*/单行多用于为成员函数编写业务逻辑文档或是声明临时变量。/ 从1995年开始，对所有超过1000美元的/发票提供5的折扣本规范规定：对于所有的接口、类、

5、成员函数必须提供文档注释，使用C类型的注释来标注旧的代码和调试时使用，利用单行注释来注释业务逻辑以及对临时变量的说明。1.3.1 javadoc概要以后再说吧2. 成员函数标准成员函数的相关注释2.1 成员函数命名规范成员函数的命名采用完整的英文描述方式来编写，其中第一个英文单词的首字母采用小写，之后的单词的首字母大写。举例：openAccount()printMailingLabel()save()delete()2.1.1 Getter函数的命名Getter函数用于返回属性的值。此类函数的命名规范是在属性名称的前面添加get前缀。例如：getFirstName()getAccountNum

6、ber()getLostEh()2.1.2 Setter函数的命名Setter函数用于设置属性的值，此类函数的命名规范是在属性名称的前面添加set前缀。举例：setFirstName(String aName)setAccountNumber(int anAccountNumber)setReasonableGoals(Vector newGoals)setPersistent(boolean isPersistent)setAtEnd(boolean isAtEnd)2.1.3 构建函数构建函数必须与类名完全相同，这是Sun定义的规范！例如Customer类的构建函数为Customer（）。

7、2.2 成员函数的可视性一个好的设计要尽量减少类之间的耦合，因此，对于成员函数的可视性必须尽量采用严格的策略，不必public的，采用protected，不必protected的，采用private。可视性说明适用条件publicpublic的成员可以被其它所有的对象或类调用当成员函数要被类的继承层次之外的对象或类访问时protectedprotected的成员函数只能被这个类的子类访问当成员函数仅仅在类的继承层次上需要，对外部不需要时。privateprivate的成员函数只能被这个类中的成员函数访问，它的子类也不能访问当成员函数仅仅在类内部使用时。如果没有指明可视性，则采用缺省的或包（pa

8、ckage）内可视性。这个成员函数对本包内的所有类公开（public），但对于包外的类保持private。仅当您需要在一个包内实现一个内聚性很强的业务逻辑时，考虑使用这种方式。2.3 成员函数的题头在每个成员函数代码的上面都应该编写成员函数文档，其中描述的是对这个成员函数的说明。题头中的内容包括如下几个方面：l *明确这个成员函数的用途，描述这个成员函数使用时的上下文环境。l *解释成员函数的参数的含义，以及如何使用这些参数。javadoc中的param标记就是用于标记参数。l *成员函数的返回值。利用javadoc中的return标记。l 已知的bug。表明成员函数的弱点。l 成员函数抛出的

9、例外。便于其它程序员在他们的代码中捕捉（catch）。利用javadoc的exception标记。l 成员函数如何影响对象。例如对于银行帐户对象的withdraw()函数，应当表明它更改了帐户余额。l 包括历史代码的更改。如果对成员函数进行了大的变化，则要表明更改了什么内容（在我们开始使用版本控制软件后，可以不包括这一内容）。l 如果成员函数的调用方式不太直观，或是有特别注意的地方，则利用例子进行说明。l 所有的并发性问题。如果您在编码中出现了并发性问题、使用了同步等方式，则要对本函数中的所有并发性问题进行说明。以上内容仅供参考，并不一定适合所有的成员函数，可根据具体情况确定，原则就是尽量让别

10、人能看懂你的代码，并易于维护和改善。但是其中前三项必须注明，除非没有参数，或是没有返回值。2.4 内部注释除了函数题头外，还要在成员函数的内部使用注释，这在前面的基础部分中已经说明了各种注释方式用途，这里强调指出：由于C类型的注释与题头的注释十分相似，因此，除了用于注释掉不再使用的代码以及简短表述编写者的意图之外，尽量少使用。对于业务逻辑的注释，统一采用单行注释。在函数体的内部，您应当注释的内容是：l 控制结构。描述每一个控制结构所完成的内容。描述的详细程度要达到：以后阅读代码时无需阅读所有的代码，只需阅读这一结构之前的注释即可了解它所完成的功能。l 对于关键代码段，尤其是关键性的算法以及带有

11、数字（魔术数字）的地方，除了需要注释说明完成的内容之外，还要标明为什么这样做。l 局部变量。后面还有详细的说明变量的内容。这里仅仅指出：成员函数内部定义的每个局部变量，都需要在这个变量的后面，用单行注释说明它的用途。l 对于困难或复杂的代码，会影响别人的阅读，要求必须有更为详细的文档说明。l 如果在代码段中的有严格先后执行顺序的语句，尤其是多个成员函数的调用有先后顺序时，必须加以说明。建议：对于“”号，在它的后面标注结束的内容，例如/end if，/end for, /end switch，这样程序的可读性会更好。2.5 编写干净的代码的技巧1 在您的代码中加注释（文档化）2 将您的代码分段，

12、并使用缩进要求：对于位置，采用下例子所示的风格，即与起始语句位于一行。public SearchResults() status = new Status();results = new SearchResultBean0;3 对于很长的语句，进行断行处理，折下去的一行要使用缩减处理，以表明与上面一行是一个整体，例如BankAccount newPersonalAccount = AccountFactory createBankAccountFor( currentCustomer, startDate,initialDeposit, branch);4 使用空白，例如不好的代码：count

13、er=1;grandTotal=invoice.total()+getAmountDue();grandTotal=Discounter.discount(grandTotal,this);好的代码：counter = 1;grandTotal = invoice.total() + getAmountDue();grandTotal = Discounter.discount(grandTotal, this);5 遵循30秒规则这是一个建议性原则，就是尽量保证你的函数能让别人在30秒内看懂。呵呵，这个规则有时有些难度，尽力吧。6 编写简短、单行的语句这是一个建议性规则。就是尽量在一行内完成

14、任务，不要将代码的长度超过可视屏幕，如果你发现你的代码太长，那你基本上需要重新考虑算法。3. 属性相关标准3.1 属性的命名在命名时采用完整的描述（无论英文，还是拼音）。对于arrays或vectors，应当在名称中就标记为复数。第一个单词的首字母小写，其后的单词的首字母大写。如果第一个单词是一个缩写（例如sql），则整个缩写都采用小写，不要有的使用小写，有的使用大写。举例：firstNamezipCodeunitPricediscountRateorderItemssqlDatabase3.1.1 命名图形控件对于界面图形控件的命名，要在名称的后面标注完整的控件的名称。举例：okButton

15、customerListfileMenunewFileMenuItem3.1.2 常量的命名Java中常量的声明是在变量的定义的前面加上static final修饰符号。所有的单词都采用大写，单词之间用下划线间隔。举例：MINIMUM_BALANCEMAX_VALUEDEFAULT_START_DATE3.1.3 集合类型的命名对于集合类型的变量，要用复数表示。举例：customersorderItems3.2 属性的可视性可视性说明合理使用publicpublic属性可以倍其它所有对象或类访问尽量不要使用publicprotectedprotected属性可以这个类以及它的子类的成员函数访问

16、尽量不要使用protectedprivateprivate属性只可以被自己所在的类中的成员函数访问，子类也不能访问尽量将所有的属性设置为private，并通过getter和setter成员函数（访问函数）来读取和设置各个属性。在实体EJB中，如果属性不是永久性的（即不会存储到数据库中），您应当将这些属性标记为transient。3.3 属性的注释每个属性都应当书写足够的注释，以便其它程序员方便地了解。为保证提供有效的注释，您应当编写如下内容：1 属性的说明。您需要对属性进行说明，以便其它人可以了解如何使用它。2 举例。对于与复杂的业务逻辑相关的属性，您需要提供多个举例值。3 并发问题。如果您在

17、编程中利用了Java的并发编程功能，您应当提供完整的文档来说明。3.4 使用访问函数访问函数主要用于更新和获取某个属性的值。主要有两种：setter和getter。setter函数用于更改变量的值，getter用于获取变量的值。尽管访问函数增加了代码的任务量，但这种方式封装类中的实现细节，并且更易于维护。因此，除非特别需要，都希望利用这种方式。注意：如果您采用了setter和getter函数来访问变量，虽然您的确可以在其它成员函数中直接访问这个变量，但不要这么使用，也要通过访问函数来操作变量。3.4.1 访问函数的命名getter成员函数的命名方式是get属性名称，但有一个例外就是：对于boo

18、lean型的属性，getter的命名方式是is属性名称。setter成员函数的命名方式：set属性名称。注意：其中属性的名称的首字母要大写。举例：属性类型getter函数名setter函数名firstNamestringgetFirstName()setFirstName()addressAddressObjectgetAddress()setAddress()persistentbooleanisPersistent()setPersistent()orderItemsArray of OrderItem objectsgetOrderItems()setOrderItems()对集合类型的

19、变量的访问函数的特别说明：集合类型（例如array和vector）等，除了set和get函数之外，还可以补充“插入”，“添加”和“删除”三个访问函数。成员函数的类型命名规范举例集合类型的getter函数getCollection（）getOrderItems（）集合类型的setter函数setCollection（）setOrderItems（）向集合中插入对象insertObject（）insertOderItem（）从集合中删除对象deleteObject（）deleteOderItem（）创建并添加一个新的对象newObject（）newOrderItem（）3.4.2 使用访问函数的一

20、些好处1 通过一个入口来更新属性的值2 便于控制如何访问属性的值，例如可以控制谁可以访问某个属性3 可以用来初始化属性的值4 减少了子类和父类之间的耦合5 当更新一个属性时，可以方便地考虑业务，例如可能会同时更新其它属性6 简化了并发性问题。setter函数就是控制并发性的很好的地方3.5 别忘记初始化Static属性如果某个属性是静态的，别忘了在定义时就为它赋值。4. 局部变量标准4.1 局部变量的命名局部变量的命名方式基本与属性的命名方式相同。但是为了方便，有些特殊类型的局部变量的命名方式有所不同：l 流l 循环变量l 例外4.1.1 流的命名对于在一个成员函数内打开、使用并关闭的输入或输

21、出流，常用的命名方式是使用in和out来作为这些流的名字。如果一个流同时作为输入和输出，则可以采用inOut的名称。这种方式也是Sun建议的方式。但我们建议，利用inputStream、outputStream和ioStream这三个变量来代替上面的三个变量。4.1.2 循环变量的命名我们推荐仍然沿用大家经常采用的i、j和k等单字母命名方式，但也不排斥采用类似loopCounter等的命名方式。4.1.3 例外对象的命名因为在Java代码中常常使用字母e来作为例外对象，因此我们也使用e作为通用的例外命名方式。4.2 局部变量的声明和注释局部变量的声明和注释遵循如下规范：1 每行仅声明一个变量。

22、2 在变量声明的行尾，用/注释方式表明变量的用途。3 尽量将一个局部变量仅用于一个用途。以便其它程序员更容易理解您的代码。5. 成员函数的参数 标准5.1 参数的命名参数的命名与局部变量的命名方式相同。举例：customerinventoryIteminputStreame5.2 参数注释对于成员函数的参数的注释，应通过javadoc param标记，放置在成员函数的题头注释中。注释中应当描述：1 参数的用途。2 对参数的限制。例如正数，或字符串的长度不超过5个。3 在参数的调用方式不是很明显的情况下，应当提供参数值的举例。简单例子：/* * Process the specified HTT

23、P request, and create the corresponding HTTP * response (or forward to another web component that will create it). * Return an ActionForward instance describing where and how * control should be forwarded, or null if the response has * already been completed. * * param mapping The ActionMapping used

24、 to select this instance * param actionForm The optional ActionForm bean for this request (if any) * param request The HTTP request we are processing * param response The HTTP response we are creating * * exception IOException if an input/output error occurs * exception ServletException if a servlet

25、 exception occurs */6. 类、接口、包的标准6.1 类标准6.1.1 类的可视性类的可视性有两种：public和package（缺省）。public 的可视性是通过关键字public来指定，package的可视性不用指明，是缺省值。public的类，其它类中都可以使用，但package的类只能在同一个包中的类中使用。原则上是尽量使用package，仅对于对外提供统一接口的类使用public的可视性。6.1.2 类的命名类的命名尽量采用完整的描述（能表述类的含义），第一个字母要大写。举例：CustomerOrderOrderItemFileStream6.1.3 类的注释在类

26、的定义之前（紧挨着类的定义）应当提供如下内容的注释：1 类的用途。表述类的用途等相关信息，对于类中的一些限制条件，也应加以描述。2 已知的bug。如果类的设计中有明显的缺陷，应当指明。另外，还要说明为什么没有解决这个bug。注意，如果bug是针对某个成员函数的，则应当将这个bug放到成员函数之前的说明中。3 这个类的开发/维护历史。说明修改者、日期以并概要描述所做的改动。4 并发策略。每个实现Runnable的类都要完整描述它的并发策略。通用的解决并发的策略有：Synchronized objects，balking objects，guarded objects，versioned obje

27、cts，concurrency policy controllers和acceptors。（呵呵，Jeff对这些策略了解得也不多，大家查资料吧，这里算是抛砖引玉）简单例子：/* * An ActionForward represents a destination to which the * controller servlet, ActionServlet, might be directed to * perform a RequestDispatcher.forward() or * HttpServletResponse.sendRedirect() to, as a result

28、of * processing activities of an Action class. Instances of this * class may be created dynamically as necessary, or configured in association * with an ActionMapping instance for named lookup of potentially * multiple destinations for a particular mapping instance. * * An ActionForward has the foll

29、owing minimal set of properties. * Additional properties can be provided as needed by subclassses. * * name - Logical name by which this instance may be * looked up in relationship to a particular ActionMapping. * path - Context-relative URI to which control should * be forwarded, or an absolute or

30、relative URI to which control should * be redirected. * redirect - Set to true if the controller * servlet should call HttpServletResponse.sendRedirect() * on the associated path; otherwise false. false * * * author Craig R. McClanahan * version $Revision: 1.4 $ $Date: 2001/02/21 00:35:44 $ */6.1.4

31、类的声明6.1.4.1 成员函数和属性的排列顺序大家采用统一的顺序，会便于代码的阅读。推荐采用如下顺序：构建函数finalize()public属性private属性public的成员函数protected的成员函数private的成员函数对于上面列表中的每一部分中，按字母的顺序排序（由AZ）。6.1.5 最小化Public和Protected 接口好处多多：1 学习使用快。看看public接口就基本知道怎么使用了。2 减少耦合。public的接口少了，自然耦合程度低了。3 更大的灵活性。原因与2 相同。类封装的越严密，自然内部改动时灵活性就大了，不必过多考虑对外界的影响啊。说明：您可以首先编

32、写public接口，如果您不清楚该写什么接口（服务和动作），那说明你还有一些设计工作要做。6.2 Interface标准总体评价：如果你不熟悉Interface，那就不要使用Interface。6.2.1 Interface的命名命名方式也采用首字母大写的方式，Interface的名称往往是一些形容词，例如Runnable和Clonealbe，但也有名词的形式，例如Singleton或DataInput。6.2.2 Interface的注释1目的。描述这个Interface的用途。2什么时候使用，什么时候不用。因为interface中定义的都是成员函数的名字，因此第2章中对成员函数的说明也适用

33、于接口中的成员函数。6.3 Package 的标准6.3.1 Package的命名1 各个单词之间用“.”来间隔。2 Sun提供的标准Java包的名称是以java或javax开头。Sun保留了这一权利，因此，您就别这样命名了。3 包的名称建议不要全是大写，尽量使用小写。4 企业内部使用而且不给其它企业使用的包，可以自己定义名称。例如persistence.mapping.relational和interfaces.screen。对于要给其它企业使用的包，命名的开头采用倒写Internet域名的方式，例如com.sinosoft.embed.product.material。5 包的名称是单数，对于包interface.screen，不要使用interface.screens的形式。6.3.2 包的文档应当提供专门的文档来描述包的用途。对于每个包，您应当描述：1 包的基本用途。便于其它程序员了解如何使用这个包，以及是否需要增强或扩展这个包。2 包内的类。概要列出包内所有的类和Interface。- 17 -