javaguide.doc

质量管理运作体系文件修订控制页章节编号章节名称修订内容简述修订日期修订前版本号批准人211 介绍1.1 为什么要制定编码规范编码规范的重要性如下：l 对一个软件来说，维护费用占它整个生存周期全部花费的80%。然而，几乎没有一个软件在它的整个生命周期中都是有原班人们维护的。l 编码规范化提高了程序的可读性，能够让工程师更快，更透彻的理解程序代码 。l 如果要将你的程序源代码作为一件产品，应该象其他产品一样经过很好的包装，清楚明晰。1.2 感谢这份文档反映了由Sun Microsystems, Inc 制定的JAVA语言的编码标准。主要的贡献者是：Peter King, Patrick Naughton, Mike DeMoney, Jonni Kanerva, Kathy Walrath, and Scott Hommel2 文件命名这一部分列出了常用文件的后缀及其命名规范。2.1 文件后缀命名Java程序使用一下文件后缀命名方法： 文件类型 后缀源代码 .java编译后的二进制代码.class 2.2 普通文件命名经常用的文件名包括： 文件名用途 GNUmakefileMakefiles文件的首选文件名.我们用 gnumake 来build我们的源程序. README概述某一目录的内容 3 文件组织一个文件包含了几个由空行和注释分隔而成的代码块。应尽量避免一份文件超过2000行代码。规范的Java源程序，请参看附录的“Java Source File Example”3.1 Java源文件每个Java源文件都包含一个单一的公共类或者接口。当私有的类或接口与一个公共类有关联时，应把它们跟这个公共类放在同一个源文件中。这个公共的类或者接口应该是文件中的第一个类或接口。Java源文件应按如下顺序组织：文件开头的注释（参看“文件注释” 部分）Package and Import 语句Class and interface 声明（参看“Class and interface 声明”部分） 3.1.1 文件开头的注释所有的源文件都应以 “C”语言风格的注释在文件的开头列出 类名，版本信息，编写日期，版权声明等信息。/* * Classname * * Version information * * Date * * Copyright notice*/3.1.2 Package and Import 语句Java源文件的第一行非注释语句通常是 package 语句，接下来是 import 语句。例如：package java.awt;import java.awt.peer.CanvasPeer;注意：package名的第一部分通常以ASCII小写字母来表示，且应是一级域名如：com, edu, gov, mil, net, org,或者是ISO Standard 3166, 1981规定的两个英文字母表示的国家代码。3.1.3 Class and Interface 声明下表按照应出现的先后顺序描述了一个类或接口的声明。参看“Java Source File Example”中关于注释的例子。Class/Interface 声明备注1Class/interface 的文档注释 (/*.*/) 参看“5.2 文档注释” 2Class or interface 语句 3关于Class/interface 是如何实现的注释 (/*.*/),如果有必要的话。 这部分注释应包含类或接口范围内的信息，这些信息不适于写在class/interface的文档注释里。4类变量（static）首先是”public”类变量, 然后是”protect” 类变量, 然后是”package”级类变量, 最后是”private”类变量。5实例变量首先是”public”类变量, 然后是”protect” 类变量, 然后是”package”级类变量, 最后是”private”类变量。 6构建器 7方法方法应按功能而不是范围或访问能力来分组。如：一个私有方法可以介于两个公共实例方法之间。总的目标是使源码更易读，更好理解。 4 缩排及留空规定缩排时应以4个空格为单位，留空可以用“space”键也可以用“tab”键。使用“tab”键时应设定一个“tab”为8个空格，而不是4个。4.1 每行的长度每行源代码的长度不应超过80个字符。4.2 换行当一个表达式无法用一行写完时，按照以下的原则来换行：l 在逗号后换行。l 在操作符前换行。l 从高一级（运算符）而不是低一级处换行。l 让新的一行从上一行的同一级处开始。l 如果上述规则导致代码混乱或者代码压到了右边距，可以采取从头缩排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个空格以避免太往里缩排了INDENT 8 SPACES TO AVOID VERY DEEP INDENTSprivate static synchronized horkingLongMethodName(int anArg, Object anotherArg, String yetAnotherArg, Object andStillAnother) .行的缩进应尽量采用缩进8个空格的规则，使用缩进4个空格的规则会导致语句体浏览起来比较困难。例如：/避免使用这种缩进方法if (condition1 & condition2) | (condition3 & condition4) |!(condition5 & condition6) /BAD WRAPS doSomethingAboutIt(); /MAKE THIS LINE EASY TO MISS /USE THIS INDENTATION INSTEADif (condition1 & condition2) | (condition3 & condition4) |!(condition5 & condition6) doSomethingAboutIt(); /OR USE THISif (condition1 & condition2) | (condition3 & condition4) |!(condition5 & condition6) doSomethingAboutIt(); 这里是规范三目运算符表达式书写的三种方法：alpha = (aLongBooleanExpression) ? beta : gamma; alpha = (aLongBooleanExpression) ? beta : gamma; alpha = (aLongBooleanExpression) ? beta : gamma; 5 注释Java 程序有两种类型的注释：实现注释（implementation comment）和文档注释(documentation comment)。实现注释以/*.*/和/来区分，类似于C+。文档注释仅JAVA独有，以/*.*/来区分。文档注释能通过 javadoc 工具转换成HTML文件。实现注释用来注释掉部分源码或者说明程序的详细实现过程。文档注释从一个与实现无关的角度来描述源代码的有关规格。注释用来给出对代码的总的看法，提供代码本身不能提供的信息。注释应只提供有助于阅读和理解程序相关的信息。例如，关于相应的包如何“build”,它在哪个目录等信息就不应包括在注释里。应避免代码已经改动而注释却已经过时的情况出现。注意：注释的频率有时反映了代码的质量，注释太多可能意味着你的代码质量很差。如果你感到非要增加一段注释不可，还不如重写代码来得更清晰。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 类，接口，构建器，方法，作用域等。每个文档注释都用分隔符“/*/”包括起来，每个类，借口，或者成员可以有一个文档注释。文档注释应当出现在声明的前面。如：/* * The Example class provides . */public class Example .注意：高一级的类和接口不需要缩进，但他们的成员需要缩进。类或者接口的文档注释的第一行不需要缩进，但随后的文档注释行需要向内缩进一个空格以保证“*”对齐。成员，包括构建器的文档注释的第一行要向后缩进4个空格，随后的各行向后缩进5个空格。如果你需要给出关于一个类，接口，变量或者方法的相关信息，但这些注释写在文档注释里又可能不太合适，那么你可以将它放在声明之后的实现注释或者单行注释里。例如，关于类是如何实现的详细信息就可以放在类声明语句之后，而不是在类的文档注释里。文档注释不能放在方法或者构建器的定义区内，因为Java将文档注释与注释之后的第一个声明相联系起来了。6 声明6.1 每行的声明个数建议每行只声明一个变量，这样便于在其后作相应注释。换句话说，就是int level; / indentation levelint size; / size of table要比： int level, size;清晰不要把不同类型的变量放在同一行里声明，如： int foo, fooarray; /WRONG!注意：以上例子使用空格把变量类型与变量标识分开，也可以使用“tab”来分隔变量类型与变量标识，如： intlevel; / indentation levelintsize; / size of tableObjectcurrentEntry; / currently selected table entry6.2 初始化尽量在声明局部变量是对其进行初始化。如果变量的初始值依赖于计算的来的话，可以不进行初始化。6.3 位置应把声明放在代码块的开头。（一个代码块是指被“”和“”包括起来的所有代码）尽量在开始就声明所要使用的变量，以增强可移植性。void myMethod() int int1 = 0; / beginning of method block if (condition) int int2 = 0; / beginning of if block . 一个例外是“for循环”，在循环语句里可以声明变量类型：for (int i = 0; i = 0) ? x ： -x;10.5.4 特殊注释Use XXX in a comment to flag something that is bogus but works. Use FIXME to flag something that is bogus and broken. 11 编码实例下面的例子向我们表明了怎样按照格式来写一份含有一个公共类的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 commen