java编码规范

Java 编码规范

翻译：王士勇

（转载请保留作者，谢谢）

1.   引言

1.1. 为什么要编码规范

编码规范为什么是重要的？有以下一些理由：

l         一份软件80%的生命周期是维护期

l         任何软件都很难说他的整个生命周期都是由他的原始作者来维护

l         编码规范改善软件的可读性，使得软件工程师充分理解新的代码变得非常的快速。

l         如果你要把你的原码作为产品发布，你需要确保他像你的其他产品一样干净并且封装的好。

为了按照规范工作，每个人写软件的时候，都必须遵守编码规范。记住，是每个人！

1.1.1.    致谢

这本书是反映的是Java Language Specification 中关于java语言编码规范的。在这里要着重对Peter king ,Patrick Naughton,Mike DeMoney,Jonni Kanerva,Kathy Walrath,和Scott Hommel表示感谢。

2.   文件名

这一节列出了本书所用的大部分文件名和后缀。

2.1. 文件后缀

        .java    java 源文件后缀

        .class     java 字节码文件后缀

2.2. 常用的文件名

        经常使用的文件名包括以下：

       GNUmakefile             首选的makefile的名字，我们使用gnumake来build我们的软件。

       README                    那些专门概述特定文件夹内容的文件的首选的名字

3.   文件的组织

一个文件的各个部分之间应该用空行隔开，并且应该用一个可选的注解来标示每个不同的部分。

文件超过2000行，是非常笨重讨厌（cumbersome）的，应该避免。

至于java 编程的正确格式的示例，请参看18页上的”JAVA Source File Example(Java 原码文件示例)”。

3.1. Java 源码文件

        每一个Java源码文件都包括一个唯一的public 类或interface。当私有的类和interface 都和这个public 类有关联时，你可以把它们放到这个public 类的源文件中。这个public 类或interface 应当是这个文件的第一个类或interface 。

 

Java 源文件有以下的顺序：

l         文件开头注解（参见第二页的“Beginning Comments（开头注解）”）

l          声明package 的语句和载入语句。

l         类和interface的声明（参见page 3的“Class and Interface Declarations”）

3.1.1.    开头注解

       所有的源文件都应该以一个C语言风格的注解开头。这个注解应该列出类名，版本信息，日期和版权声明：

       /*

       *Classname

       *

       *Version information

       *

       * Date

*

 * copyright notice

 *

 */

3.1.2.    声明包的语句和import 语句

       绝大多数java 源文件中的第一非注释行应该是声明包的语句。此后，紧接着是import 语句。例如：

              package java.awt;

              import java.awt.peer.CanvasPeer;

3.1.3.    类和接口的声明

下面的表格描述了部分的类和接口的声明，他们应该按照表格的顺序。参看“Java Source File Example” on page 18 。

                           

部分类/接口声明	注释
类/接口文档注解/**…*/	如何做此类注解请参看“Documentation Comments”
类或接口声明
类/接口实现的注解（/*。。。*/），如果有必要的话	这个注解应该包括任何整个类或接口范围内的不适合在类/接口文档注解中出现的内容。
类（静态）变量	首先是public类变量，然后是protected类变量，然后是friendly(package level,即默认)。然后是private变量。
Instance variables(译注：实体变量？不会翻译了，意即普通的变量。)	首先是public,其次protected,接着package level。最后是private变量。
类的构造函数
方法，（译注：即类的成员函数）	这些方法应该以功能相近为标准，组织在一块，而不是看其作用域和可存取性。例如：一个private class 方法（译注：意即private static method）可以被放在两个public instance 方法（译注：意即public method）中间。其目的是为了代码可读性和可理解性增加。

4.   缩进

应该以四个空格为缩进的最小单位，缩进的精确结构没有被详细定义。Tabs必须被精确指定为8个空格（而不是4个）。

4.1. 代码行的长度

应避免行的长度超过80个字符，因为很多的终端和工具都不支持超过80个字符。（译注：个人认为现在一般都支持行超过80个字符，但是由于超过80个字符，一般要滚屏，所以尽量还是不要超过此限制。）

注意：文档中的例子的行长度应该更短，一般不超过70个字符。

4.2. Wrapping lines(断行的方法)

当一个表达式不适合一个单行时，依照以下这些一般性的原理来断行：

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;     //       AVOID(应该避免这样)

下面是两个方法声明的断行的例子，第一个是规范的例子。第二个如果要使用规范的缩进的话，将会使第二和第三行缩进的非常向右。所以仅仅使用8个空格来替代。

              //规范的缩进

              someMethod ( int anArg, Object anotherArg, String yetAnotherArg,

                                   Object andStillAnother){

                     …

              }

 

              //以8个空格来缩进，以避免非常纵深的缩进

              private static synchronized horkingLongMethodName(int anArg,

                        Object anotherArg, String yetAnotherArg,

                        Object andStillAnother) {

                    …

              }

       行的包装（Line wrapping for）对if 语句一般应该用8个空格规则，因为标准的（4个空格）缩进使得if 的主体部分非常难看明白。例如：

              //不要使用这种缩进

              if ( ( condition1 && condition2)

                  || (condition3 && condition4)

                     || ( condition5 && condition6)) { //差的包装

                     doSomethingAboutIt();

       }

              //以这种缩进方式代替

              if ( ( condition1 && condition2)

                      || ( condition3 && conditin4 )

                                   || ! (condition5　&& condition6)) {

                            doSomethingAboutIt();

              }

              //或者这样使用

              if ((condition1 && condition2) || (conditin3 && condition4)

                        || ! ( condition5 && condition6 )) {

                     doSomethingAboutIt();

              }

       这儿有三种可接受的三元运算符的缩进格式：

              alpha = ( aLongBooleanExpression) ? beta : gamma;

              alpha = ( aLongBooleanExpression) ? beta

                                                                : gamma;

              alpha = ( aLongBooleanExpression)

                       ? beta

                       : gamma;

 

5.   注释（注解）

待译。