Java语言编码规范Sun.pdf Java编码规范第一参考和知道资料
1.介绍( Introduction) 1.1为什么要有编码规范( Why Have Code Conventions) 编码规范对」程序员血言尤为重要,有以下儿个原因 一个软件的生命周期中,80%的花费在于维护 几乎没有仟何一个软件,在其整个生命厝期屮,均山最初的开发人员来维护 编码规沱可以改善软件的可读性,可以让程序员尽快而彻底地理解新的代码 -如果你将源码作为产品发布,就需要确任它是否被很好的打包并且清晰无误,一如你已构建的 其它仁何产品 为了执行规汽,行个软件丌发人员必须致遵守编码规范。每个人。 12版权声明( Acknowledgment 本文档反映的是 Sun Micro Systems公司,Java语言规范屮的编码标准部分。主要页献者包 FEE: Peter King, Patrick Naughton, Mike DeMoney, Jonni Kanerva, Kathy Walrath 以及 Scott hommel。 本文档现由Scotthomme维护,有关评论意见请发至homme@eng.sun.com 原文出处:htp://java. sun. com/docs/ codeconv/htm/ Codeconvtoc. doc. htm, 译文出处http://morningspace.51.net/,moyingzz@etang.con 译者晨光( Morning) 2.文件名( File Names) 这部分列出了常用的文件名及其后缀。 2.1文件后缀( File suffixes) Java程序使用下列文件后缀: 文件类别 文件后缀 Java源文件java Java字节码文件cass 22常用文件名 Common file names) 常用的文件名包括 文件名 用途 GNUmakefi| le makefiles的首选文件名。我们采用 gnumake来创建(buid)软件。 README概述特定日录下所含内容的文件的首选文件名 3.文件组织( File Organization 个文件由被空行分割而成的段落以及标识每个段落的可选注释共同组成。超过2000行的程 序难以阅读,应该尽量遆免。"]ava源文件范例"提供了一个布局合理的Java释序范例 3.1Java源文件( Java Source Files) 每个]ava游文件都包含一个单一的公共类或接口。若私有类和接口与一个公共类相关联,可以 将它们和公共类放入同一个源文件。公共类必须是这个文件中的第一个类或接口。 Java源文件还遵循以下规则 开头注释(参见"开头注释" 包和引入语句(参见"包和引入语句") -类和接口声明(参见"类和接口声明") 3.1.1开头注释( Beginning Comments) 所有的源文件都应该在开头有一个C语言风格的注释,其中列出类名、版本信息、日期和版权 声明 / 冰 Classed 半 米 Version information k Date k Copyright notice / 312包和引入语句( Package and Import Statements) 在多数]ava源文件中,第一个非注释行是包话句。在它之后可以跟引入语句。例如: package java. awt import java. awt. peer. CanvasPeer 313类和接口声明(c| ass and Interface declarations) 下表描述了类和接口声明的各个部分以及它们出现的先后次序。参见"Java源文件范例"中一个 包含注释的例子。 类/接口声明的各部分注解 类/接口文档注释 该注释中所需包含的信息,参见"文档注释 2类或接口的声明 类/接口实现的注释 /)如果有必要的 该注释应包含任何有关整个类或接口的信息,而这些信息又不适合 作为类/接口文档注释。 4类的(静态)变量 首先是类的公共变量,随后是保护变量,再后是包一级别的变量(没 有访问修饰符, access modifier),最后是私有变量。 首先是公共级别的,随后是保护级别的,再后是包一级别的(没有访 5实例变量 问修饰符),最后是私有级别的。 6构造器 这些方法应该按功能,而非作用域或访问权限,分组。例如,一个 7方法 私有的类方法可以置于两个公有的实例方法之间。其日的是为了更 便于阅读和理解代码 4.缩进排版( Indentation) 4个空格常被作为缩进排版的一个单位。缩进的确切解释并未详细指定(空格vs.制表符)。 个制表符等于8个空格(而非4个) 4.1行长度( Line Length) 尽量避免一行的长度超过80个字符,因为很多终端和工具不能很好处理之。 注意:用于文档中的例子应该使用更短的行长,长度一般不超过70个字符。 42换行( Wrapping Lines) 当一个表达式无法容纳在一行内时,可以依据如下一般规则断开之 在一个逗号后面断开 在一个操作符前面断开 宁可选择较高级别( higher- level)的断开,而非较低级别( lower- -level)的断开 新的一行应该与上一行同一级别表达式的开头处对齐 如果以上规则导致你的代码混乱或者使你的代码都堆挤在石边,那就代之以缩进8个空格。 以下是断开方法调用的一些例了 SOme Me thod (longExpressionl, longExpression2, longExpression3 longExpression1, longExpression5 var= sOme Me thodI(longExpressionl someMethod2 (longExpression2 longExpression3)) 以下是两个断开算术表达式的例子。前者更好,因为新开处位于括号表达式的外边,这是个较高 级别的断开。 longNamel= longName 2 *(longName 3+ longName4-longName5) +4* longname6;//PREFFER longName1- longName 2 (longName 3+ longName1 longName5)+ 4 a longname6 L/AVOID 以下是两个缩进方法声明的例子。前者是常规情形。后者若使用常规的缩进方式将会使第二行和 第三行移得很靠右,所以代之以缩进8个空格 //CONVENTIONAL INDENTATION some Method (int anArg, Object anotherArg, String yetAnotherArg Object andStillAnother)i Z/INDENT 8 SPACES TO AVOID VERY DEEP INDENTS private slavic synchronized horkingLongMe thodName (int anArg Object anotherArg, String yetAnotherArg Object andStillAnother)I if语句的换行通常使用8个空格的规则,因为常规缩进(4个空格)会使语句体看起来比较费劲。 比如 //DON T USE THIS INDENTATION if ((condition1 & condition2) (conditions & condition4) conditions & condition6))(//BAD WRAPS doSomethingaboutito //MAKE THIS LINE EASY TO MISS //USE THIS INDENTATION INSTEAD if ((condition1 & condition2) (condition 3 & condition4 .(condition 5 & condition6)) dosomethingAboutIto //OR USE THIS if ((conditionl & condition2 condition 3 & condition4) !(conditions & condition6))( doSome thingAboutltO 这里有三种可行的方法用于处理三元运算表达式 alpha -(aLongboolean Expression)? beta: gamma alpha =(aLongBooleanExpression)? beta gamma alpha-(aLongBooleanExpression) ? beta gaima 5.注释( Comments) ava程序有两类注释:实现注释( implementation comments)和文档注释( document comments)。实现注释是那些在C++屮见过的,使用/*,*/和/.定的注释。文档汁释(被称 为" doc comments")是Java独有的,并由/**,*/界定。文档注释可以通过 javadoc工具转 换成HTML文件。 实现汴释用以注释代码或者实现细节。文档注释从实现自由( implementation-free)的角度描 述代码的规汽。它可以被那些手头没有源码的开发人员读懂 注释应被用来给出代杩的总括,并提供代码自身没有提供的附加信息。注释应该仅包含与阅读和 彈解稈序有关的信息。例如,相应的包如何被建立或位于哪个日录下之类的信息不应包括在注释 中 在注释里,对设计决策中重要的或者不是显而易见的地方进行说明是可以的,但应避免提供代码 屮己清昕表达出来的重复信息。多余的的注释很容易过时。通常应避免那些代码更新就可能过时 的注释。 注意:频繁的注释有时反映出代码的低质量。当你觉得被迫要加注释的时候,考虑一下重写代码 使其更清晰 注释不应与在用星号或其他字符画出来的大框旦。注释不应包括渚如制表符和回退符之类的特殊 字符。 5.1实现注释的格式( Implementation Comment Formats) 程序可以有4种实现注释的风格:块( block)、单行( single-ine)、尾端( trailing)和行末 (end-of-line)。 51.1块注释( Block Comments) 块注释通常用于提供对文件,方法,数据结构和算法的描述。块注释被置于每个文件的开始处以 及每个方法之前。它们也可以被用」其他地方,比如方法内部。在功能和方法内部的块注释应该 和它们所描述的代码具有一样的缩进格式。 块注释之首应该有一个空行,用于把块注释和代码分割开来,比如 水 k Here is a block comment 块注释可以以/*-开头,这样 indent(1)就可以将之识别为一个代码块的开始,而不会重排它 / k Here is a block comment with some very special k formatting that i want indent (1) to ignore. *水 one two three 注意:如果你不使用 indent(1),就不必在代码中使用/*-,或为他人可能对你的代码运行 indent(1)作让步。 参见"文档注释" 5.1.2单行注释( Single-Line Comments) 短注释可以显示在一行内,并与其后的代码具有一样的缩进层级。如果一个注释不能在一行内写 完,就该采用块注释(参见"块注释")。单行注释之前应该有一个空行。以下是一个]ava代码中 单行注释的例子 if (condition) i /* Handle the condition. */ 513尾端注释( Trailing Comments) 极短的注释可以与它们所要描述的代码位于同一行,但是应该有足够的空白来分开代码和注释。 若有多个短注释出现于大段代码中,它们应该具有相同的缩进。 以下是一个Java代码中尾端注释的例子 return TRLE /*k special case * k i else return isPrime(a) /* works only for odd a水 5.1.4行末注释(End-of- Line comments) 注释界定符"//",可以注释掉整行或者一行中的一部分。它一般不用」连续多行的注释文本;然 而,它可以用来注释掉迕续多行的代码段。以下是所有三种风格的例子 if (foo >1 //Do a double-flip e l se return false / Explain why here l/ir(bar>1)i /// Do a triple-flip // el se // return false //} 52文档注释( Documentation comments) 注意:此处描述的注释格式之范例,参见"]ava源文件范例 若想了解更多,参见" How to write doc comments for javadoc",其中包含了有关文档注 释标记的信息(@ return,@ param,@see) http://iava.suncom/iavadoc/writingdoccomments/index.html 若想了解更多有关文档注释和 javadoc的详细瓷料,参见 javadoc的主页: http://iava.suncom/iavadoc/index.html 文档注释描述Java的类、接口、构造器,方法,以及字段( field)。每个文档注释都会被置于注 释定界符/**,*/之中,一个注释对应一个类、接口或成员。该注释应位于声明之前: 半半 k The Example class provides public class Example 注意顶层(top-leve)的类和接口是不缩进的,而其成员是缩进的。描述类和接口的文档注释的 第一行(**)不需缩进;随后的文档注释每行都缩进1格(使星号纵向对齐)。成员,包括构造函 数在内,其文档注释的第一行缩进4格,随后每行都缩进5格。 若你想给出有关类、接口、变量或方法的信息,而这些信息又不适合写在文档屮,则可使用实现 块注释(见5.1.1)或紧跟在声明后面的单行注释(见5.1.2)。例如,有关一个类实现的细节,应 放入紧跟在类声明后面的实现块注释中,而不是放在文档注释中 文档注释不能放在一个方法或构造器的定义块中,因为Java会将位于文档注释之后的第一个声 明与其相关联。 6.声明( Declarations 61每行声明变量的数量( Number per line) 推荐一行一个声明,因为这样以利于写注释。亦即, int level;// indentation level int size// size of table 要优」, int level, size