1、Java 编码规范Java 编码规范 .11. 说明 31.1 为什么要有编码规范 31.2 版权声明 .32. 文件名(File Names) 32.1 文件后缀(File Suffixes) 33.1 Java 源文件(Java Source Files)33.1.1 开头注释(Beginning Comments).33.1.2 包和引入(Package and Import Statements) .33.1.3 类和接口声明(Class and Interface Declarations) 34.1 行长度 .34.2 换行(Wrapping Lines) .3/ CONVENTI
2、ON INDENTATION.4Object andStillAnother) .4| !(condition5 import java.awt.peer.CanvasPeer;3.1.3 类和接口声明(Class and Interface Declarations)下表描述了类和接口声明的免修部分以及它们出现的先后次序。参见“Java 源文件范例 ”中一个包含注释的例子。类/接口声明的各部分 注解1 类/接口文档注释(/ * /)该注释中所包含的信息，参见“文档注释”2 类/接口的声明3 类/接口实现的注释(/ * /)如果有必要的话该注释应包含任何有关整个类或接口的信息，而这些信息又适合
3、作为类/接口文档注释。4 类的(静态) 变量 首先是类的 public 变量，随后是protected 变量，再后是包一级别的变量(没有访问修饰符)，最后是private 变量。5 实例变量 首先是 public 变量，随后是protected 变量，再后是包一级别的变量(没有访问修饰符)，最后是private 变量。6 构造器7 方法 这些方法应该按功能，而非作用域或访问权限，分组。4. 缩进排版(Indentation)4 个空格常被作为缩进排版的一个单位。缩进的确切解释并未详细指定( 空格 vs.制表符)。一个制表符等于 8 个空格(而非 4 个)。4.1 行长度尽量避免一行长度超过 8
4、0 个字符，因为很多终端和工具不能很好处理之。注意：用于文档是的例子应该使用更短的行长，长度一般不超过 70 个字符。4.2 换行(Wrapping Lines)当一个表达式无法容纳在一行内时，可以依据如下一般规则断开之： 在一个逗号后面断开。 在一个操作符前面断开。 宁可选择较高级别的(higher-level)的断开，而非较低级别(lower-level)的断开。 新的一行应该与上一行同一级别表达式的开头处对齐。 如果以上规则导致你的代码混乱或者使你的代码都堆挤在右边，那就代之以缩进 8 个空格。以下是断开方法的一些例子：someMethod(longExpression1, longEx
5、pression2, longExpression3, longExpression4, longExpression5);var = someMethod1(Expression1, someMethod2(longExpression2,longExpression3);以下是两个断开算术表达式的例子。前者更好，因为断开处位于括号表达式的外边，这是个较高级别的断开。longName1 = longName2 * (longName3 + longName4- longNeme5)+ 4 * longName6); /PREFFERlongName1 = longName2 * (longN
6、ame3 + longName4- longName5) + 4 * longName6; /AVOID以下是两个缩进方法声明的例子。前者是常规情形，后者若使用常规的缩进方式将会使第二行和第三行移得很靠右，所以代这以缩进 8 个空格。/ CONVENTION INDENTATIONsomeMethod(int anArg, Object anotherArg,String yetAnotherArg, Object andStillAnother) / INDENT 8 SPACES TO AVOID VERY DEEP INDENTSprivate static synchronized h
7、orkingLongMethodName(int anArg,Object anotherArg, String yetAnotherArg,Object andStillAnother) if 语句的换行通常使用 8 个空格的规则，因为常规缩进(4 个空格) 会使语句看起来比较费劲。比如：/DONT USE THIS INDENTATIONif (condition1 / MAKE THIS LING EASY TO MISS/ USE THIS INDENTATION INSTEADif (condition1 / OR USE THISif (condition1 这里有三种可行的方法用
8、于处理三元运算表达式：alpha = (aLongBooleanExpression) ? beta : gamma;alpha = (aLongBooleanExpression) ? beta: gamma;alpha = (aLongBooleanExpression)? beta: gamma;5. 注释(Comments)Java 程序有两类注释：实现注释 (implementation comments)和文档注释(document comments) 。实现注释是那些在 C+中见过的，使用/*/和/界定的注释。文档注释(被称为“doc comments”)是 Java 独有的，并
9、由 /*/界定。文档注释可以通过 javadoc 工具转换成 HTML 文件。实现注释用以注释代码或或者实现细节。文档注释从实现自由(implemtentation-free)的角度描述代码的规范。它可以被那些手头没有源码的开发人员读懂。注释应被用来给出代码的总括，并提供代码自身没有提供的附加信息。注释应该仅包含与阅读和理解程序有关的信息。例如，相应的包如何被建立或位于哪个目录下之类的信息不应包括在注释中。在注释里，对设计决策中重要的或者不是显而易见的地方进行说明是可以的，但应避免提供代码中已清晰表达出来的重复信息，多余的注释很容易过时。通常应避免那些代码更新就可能过时的注释。注意：频繁的注释
10、有时反映出代码的低质量。当你觉得被迫要加注释的时候，考虑一下重写代码使其更清晰。注释不应写在用星号或字符画出来的大框里。注释不应包括诸如制表符和回退符之类 的特殊字符。5.1 实现注释的格式(Implementation Comment Formats)程序可以有 4 种实现注释的风格：块(Block)，单行(single-line)，尾端(trailing) 和行末(end-of-line) 。5.1.1 块注释块注释通常用于提供对文件，方法，数据结构和算法的描述。块注释被置于每个文件的开始处以及每个方法之前。它们也可以被用于其他地方，比如方法的内部。在功能和方法内部的块注释应该和它们所描述
11、的代码具有一样的缩进格式。块注释之首应该有一个空行，用于把块注释和代码分割开来，比如：/ * 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*/注意：如果你不使用 indent(1)，就不必在代码中使用 / *-， 或为他人可能对你的代码运行 indent(1)让步。
12、参见“文档注释” 。5.1.2 单行注释(Single-Line Comments)短注释可以显示一行内，并与其后的代码具有一样的缩进层级。如果一个注释不能在一行内写完，就该块注释(参见“块注释”)。单行注释之前应该有一个空行。以下是一个 Java 代码中单行注释的例子：if (condition) / * Handle the condition. */5.1.3 尾端注释(Trailing Comments)极短的注释可以与它们所要描述的代码位于同一行，但是应该有足够的空白来分开代码和注释。若有多个短注释出现于大段代码中，它们应该具有相同的缩进。以下是一个 Java 代码中尾端注释的例子：
13、if (a =2) return TRUE; / * special case */ else return isPrime(a); / * works only for odd a */5.1.4 行末注释(End-Of-Line Comments)注释界定符“/” ，可以注释掉整行或者一行中的一部分。它一般不用于连续多行的注释文本；然而，它可以用来注释掉多行的代码段。以下是所有三种风格的例子：if(foo 1) / Do a double-filp.else return false;/ if (bar 1) / / Do a triple-filp./ / / else / return
14、 false;/ 5.2 文档注释(Documentation Comments)注意：此处描述的注释格式之范例，参见“Java 源文件范例”若想了解更多，参见“How to Write Doc Comments for Javadoc”，其中包含了有关文档注释标记的信息(return，param ，see) ：http:/ javadoc 的详细资料，参见 javadoc的主页：http:/ Java 的类、接口、构造器、方法，以及字段(field)。每个文档注释都会被置于注释界定符/ */之中，一个注释对应一个类、接口或成员。该注释应位于声明之前：/ * The Example class
15、 provides */public class Example 注意：顶层(top-level) 的类和接口是不缩进的，而其成员是缩进的。描述类和接口的文档注释的第一行会被置于注释的第一行(/ *)不需要缩进；随后的文档注释每行都缩进 1 格( 使星号纵向对齐 )。成员，包括构造函数在内，其文档注释的第一行缩进 4 格，随后每行都缩进 5 格。若你想给出有关类、接口、变量或方法的信息，而这些信息又不适合写在文档中，则可使用实现块注释(见 5.1.1)或紧跟在声明后面的单行注释(见 5.1.2)。例如，有关一个类实现的细节应放入紧跟在类声明后面的实现块注释中，而不是放在文档注释中。文档注释不能
16、放在一个方法或构造器的定义块中，因为 Java会将位于文档注释之后的第一个声明与其相关联。6. 声明(Declaration)6.1 每行声明变量的数量(Number Per Line)推荐一行一个声明，因为这样以利于写注释。亦即，int level; / indentation levelint size; / size of table要优于，int level, size;不要将不同类型变量的声明放在同一行，例如：int foo, fooarry; / WRONG!注意：上面的例子中，在类型和标识之间放了一个空格，另一种被允许的替代方法是使用制表符：int level; / indent
17、ation levelint size; / size of tableObject currentEntry; / currently selected table entry6.2 初始化(Initialization)尽量在声明局部变量的同时进行初始化。唯一 不这么做理由是变量的初始值依赖于某些先前发生的计算。6.3 布局(Placement)只在代码块的开始处声明变量(一个块是指任何被包含在大括号“ ”和“”中间的代码)。不要在首次用于该变量时才声明之，这会把注意力不集中的程序员搞糊涂，同时会妨碍代码在该作用域内的可移植性。void myMethod() int int1 = 0;if
18、 (condition) int int2 = 0;该规则的一个例外是 for 循环的索引变量for (int i = 0; I = 0) ? x : -x;10.5.4 特殊注释(Special Comments)在注释中使用 XXX 来标识某些方法未实现(bogus) 的但可以工作的内容。用 FIXME 来标识某些假的和错误的内容。11. 代码范例(Code Examples)11.1 Java 源文件范例 (Java Source File Example)下面的例子，展示了如何合理布局一个包含单一公共类的Java 源程序。接口的布局与其相似。更多信息参见“类和接口”以及“文档注释” 。
19、/* (#)Blah.java 1.82 99/03/18* Copyright (c) 1994-199 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 disclo
20、se 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.* verison 1.82 18 Mar 1999* author Firsname Lastname*/public class Blah extends
21、 SomeClass /* A class implementation comment can go here. */* class Var1 documentation comment */public static int classVar1;/* classVar2 documentation comment that happen to be* more than one line long*/private static Object classVar2;/* instanceVar2 documentation comment */public Object instanceVa
22、r1;/* instanceVar3 documentation comment */private Object instanceVar3;/* constructor Blah documentation comment*/public Blah() /implementation goes here/* method doSomething documentation comment*/public void doSomething() /implementation goes here/* method doSomethingElse documentation* comment* param someParam description*/public void doSomethingElse(Object someParam) /implementation goes here
