java代码规范.doc

Java语言代码规范 2 文件命名本节是列出了文件扩展名和文件命名的一般性习惯。2.1 文件扩展名JAVA软件使用以下文件扩展名: 文件类型扩展名Java源程序 .java Java字节码.class 2.2 文件命名经常使用的文件名称有: 文件名用途GNUmakefile Makefiles首选名称. 我们使用gnumake来构建软件. README Readme文件首选名称。3 文件组织组成文件的段落应当用空行分开，并且可以使用注释将每个段落标识出来。 超过2000行的文件会显示臃肿，因此应当尽量避免。 适当的JAVA文件格式，请参见 JAVA代码示例. 3.1 JAVA源文件每一个Java源文件包含一个公共的类或者接口。当私有的类和接口与这个公共的类和接口关联时，您可以将它们放到相同的文件中。公共类和接口应当是文件中的第一个类或者接口。Java源文件存在以下顺序: 文件开始处的注释 (参见 开始注释) 包和导入定义 类和接口定义 (参见 类和接口定义) 3.1.1 开始注释所有的源文件都应该以一个C风格的注释开始，注释中应当列出类名，版本信息，日期和版权声明: /* * 类名 * * 版本信息 * * 日期 * * 版权声明 */3.1.2 包和导入声明绝大多数JAVA源文件的第一个非注释行是package语句。之后, import 语句出现。如: package java.awt;import java.awt.peer.CanvasPeer;提示: 唯一包名的第一部分总是以全小写ASCII 字符书写，并且应当是顶级域名，通常是com, edu, gov, mil, net, org或者两位由英文字母标识的国家代码。国家代码由ISO Standard 3166, 1981规范指定（译者注：如中国的国家代码为cn）。3.1.3 类和接口定义下表描述了接口和类定义，定义的样式请参见Java代码示例. 类和接口定义备注1 类/接口文档注释 (/*.*/) 参见 文档注释. 2 Class或者interface 声明3 如果有必要，对类/接口编写实现注释 (/*.*/) 该注释应当包含任何接口/类信息，这些信息不适合在类/接口文档注释中出现。 4 类 (静态)变量首先是公共类变量，其次是保护变量，其次是包级别变量 (无访问修饰符), 最后是私有变量. 5 实例变量 首先是公共实例变量，其次是保护变量，其次是包级别变量 (无访问修饰符), 最后是私有变量.6 构造器 7 方法 以功能对这些方法分组比以作用域或者可访问性分组更适当. 例如, 一个私有的类方法可以在公共的实例方法之间. 其目的是使阅读和理解代码更容易. 4 缩排缩排应当以四个空格为单位. 没有强制的缩排规定 (空格vs. tabs)（译者注：这是java语言规范中定义的，在大多数的项目中，均规定以四个空格为缩排单位而不是tabs）。Tabs必须被设置为八个空格 (而不是四个). 4.1 行宽避免每行超过80字符,因为超过部分不会被许多终端或者工具处理。 注意: 文档中使用的例子应当更短，一般不要超过70个字符. 4.2 折行当一个表达式不能在一行中书写完毕时，通过以下方式折行: 在“，”后面折行. 在一个操作符前折行. 以代码层次高低决定折行，层次高的代码在同一行. 同一层次的代码左边对齐. 如果上一规则使代码变得不清晰，则统一都缩排8个空格. 以下是一些方法调用折行的示例: someMethod(longExpression1, longExpression2, longExpression3, longExpression4, longExpression5); var = someMethod1(longExpression1, someMethod2(longExpression2, longExpression3); 以下是两个算术表达式折行的例子. 第一个例子是推荐的, 因为折行发生在（）外面。longName1 = longName2 * (longName3 + longName4 - longName5) + 4 * longname6; / 更好的longName1 = longName2 * (longName3 + longName4 - longName5) + 4 * longname6; / 应当避免的 以下是两个过程定义的折行例子。第一个是常规的选择.第二个例子应该将第二行和第三行右移, 一般的，应当以8个空格进行缩排. /常规的缩排someMethod(int anArg, Object anotherArg, String yetAnotherArg, Object andStillAnother) ./缩排8个空格，以避免太深的缩排private static synchronized horkingLongMethodName(int anArg, Object anotherArg, String yetAnotherArg, Object andStillAnother) .IF语句通常应当以8个空格进行缩排，因为4空格(常规的)会使语句体看起来困难，如: /不要使用这种方式if (condition1 & condition2) | (condition3 & condition4) |!(condition5 & condition6) /BAD WRAPS doSomethingAboutIt(); /MAKE THIS LINE EASY TO MISS /应当换成这种方式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; 5 注释Java程序有两种注释: 实现注释和文档注释. 实现注释在C+中就存在了, 它们以 /*.*/, 和 /. 为分隔符。文档注释为JAVA独有, 并且以 /*.*/.为分隔符。文档注释可以被javadoc工具提取出HTML文档。实现注释表示对代码块的注释或者对代码实现细节的注释。文档注释是对代码规格进行描述。文档注释与代码实现无关（译者注：不对过程内部进行注释，只注释过程规范，如过程描述、参数及返回）. 它被没有源代码的开发者阅读（译者著：如第三方开发者）. 注释应当用来提供代码的概要信息，以及提供代码本身没有提供的额外信息。注释仅仅应当包含与阅读、理解代码有关的信息。例如：怎么构建包或者目录信息不应当包含不注释中（译者注：这些信息应当包含在readme.txt中）。 对有价值的的讨论、非显而易见的设计进行注释是必要的, 但是应当避免重复的信息出现. 随着时间的推移，重复的信息很容易成为多余注释. 一般的，需要避免任何可能过期的注释。 注意:注释的频率有时反映了低质量代码. 当您觉得需要强制加上注释时，不妨重写代码以使代码更清晰。 注释不能被加上大量的*号（译者注：如/*/这样的注释）。注释不能包含特殊字符如退格符. 5.1 实现注释的格式程序包含四种风格的实现注释: 块注释, 单行注释, 跟随注释, 和行注释. 5.1.1 块注释块注释用于提供文件、方法、数据结构、算法的描述。块注释可以在每个文件开始处或者每个方法之前使用。也可以在其他地方，如方法内使用。方法内部的块注释应当为与代码排列整齐。块注释应当以一个空行开头，以使其与其他代码区分开来。 /* * Here is a block comment. */以/*-开始的块注释不会被重新格式化。如： /*- * Here is a block comment with some very special * formatting that I want indent(1) to ignore. * * one * two * three */ 参见 文档注释. 5.1.2 单行注释短的注释可以用与代码并排的单行注释来实现。如果注释不能在一行中书写，则应当使用多行注释。 单行注释应当以空行开始. 以下是一个单行注释的例子: if (condition) /* Handle the condition. */ .5.1.3 跟随注释非常短的注释可以与代码同行,但是应当与代码隔得足够远。如果多个跟随注释与同一个代码块相关， 它们应当排列整齐. 这是一个跟随注释的例子: if (a = 2) return TRUE; /* special case */ else return isPrime(a); /* works only for odd a */5.1.4 行注释/ 注释分隔符可以注释一个完整的行或者一行的某个部分.它不应当用来对多行代码进行代码注释;无论如何，它可以用来注释掉多行代码。以下是三类型的注释例子: if (foo 1) / Do a double-flip. .else return false; / Explain why here./if (bar 1) / / Do a triple-flip./ ./else / return false;/5.2 文档注释 注意:参见 Java代码示例 . 更多详情, 参见如何为Javadoc编写文档注释，它包含了文档注释标记(return, param, see): /javadoc/writingdoccomments 更多文档注释及javadoc, 参见javadoc主页: /javadoc/ 文档注释描述Java类, 接口, 构造器, 方法, 和属性. 每一个文档注释处于 /*.*/里面, 每个类,接口, 或者方法都应当有文档注释. 注释应当出现在定义之前: /* * The Example class provides . */public class Example .注意：顶层类和接口是没有缩排的. 注释的首行 (/*)也是没有缩排的; 随后的注释行都有一个空格的缩排 (水平对齐*号). 成员（包含构造器）的注释, 首行有四个空格，随后的行有五个空格. 如果您需要给出类、接口、变量或者方法的信息，在定义之后使用块注释或者单行注释. (译者注：而不是紧跟在文档注释后面书写块注释)文档注释不应当位于方法或者构造器内部。因为会将文档注释与其后的定义（译者注：即下一个方法定义）相关联。 6 定义6.1 每行的数量推荐每行只定义一个变量，这样便于书写注释。 int level; / indentation levelint size; / size of table上面的书写方面是首选的。 int level, size;不要在同一行书写不同类型的定义，如: int foo, fooarray; /错误的!注意: 上例中，类型和实例间使用了一个空格。另一种可接受的的做法是使用tabs: intlevel; / indentation levelintsize; / size of tableObjectcurrentEntry; / currently selected table entry6.2 初始化尽量在定义时对变量进行初始化。其中一个原因是：如果不在定义时初始化，其他变量在初始化时可能会依赖该变量。 6.3 位置仅仅在块开始的地方放置定义。. (块是指由 和 围绕的代码.) 不要在变量使用时才定义; 它会使粗心的程序员搞糊涂. void myMethod() int int1 = 0; / 在方法块的开头定义 if (condition) int int2 = 0; / 在if 块的开头定义。 . 一个例外的情况是：在JAVA中，FOR循环的索引变量, 可以在FOR语句中定义: for (int i = 0; i = 0) ? x : -x;10.5.4 特殊注释在注释中使用XXX表示假的，但是可能会存在的事物. 用 FIXME 假的并且被确定不存在的事物. 11 代码示例11.1 JAVA代码示例以下是一个完事的java源文件例子:/* * (#)Blah.java 1.82 99/03/18 * * Copyright (c) 1994-1999 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 * disclose 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. * * version 1.82 18 Mar 1999 * author Firstname Lastname */public class Blah extends SomeClass /* A class implementation comment can go here. */ /* classVar1 documentation comment */ public static int classVar1; /* * cl