我翻译的《java编程规范》,第二部分。希望多多支持,给我继续的动力。

cwcoolstar 2003-08-20 04:25:00
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. 注释(注解)
待译。

...全文
41 5 打赏 收藏 转发到动态 举报
写回复
用AI写文章
5 条回复
切换为时间正序
请发表友善的回复…
发表回复
dutbreak 2003-08-20
  • 打赏
  • 举报
回复
支持!!!
TomClus8888 2003-08-20
  • 打赏
  • 举报
回复
狂彪!
freshman_csdn 2003-08-20
  • 打赏
  • 举报
回复
严重支持!THX!
  • 打赏
  • 举报
回复
噢,天哪,我的偶像终于出现了
JavaCom 2003-08-20
  • 打赏
  • 举报
回复
支持一个

62,612

社区成员

发帖
与我相关
我的任务
社区描述
Java 2 Standard Edition
社区管理员
  • Java SE
加入社区
  • 近7日
  • 近30日
  • 至今
社区公告
暂无公告

试试用AI创作助手写篇文章吧