java编码规范(2)

类别:Java 点击:0 评论:0 推荐:

Java 编码规范(2)

翻译:王士勇

(转载请保留作者,谢谢)

比上一个版本多了很多,而且排了一下版面。希望能替换掉上一篇文章

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.   注释(注解)

待译。

本文地址:http://com.8s8s.com/it/it17262.htm