Java 编码规范(2)XML:namespace prefix = o ns = "urn:schemas-microsoft-com:Office:office" />
翻译:王士勇
(转载请保留作者,谢谢)
比上一个版本多了很多,而且排了一下版面。希望能替换掉上一篇文章
编码规范为什么是重要的?有以下一些理由:
l 一份软件80%的生命周期是维护期
l 任何软件都很难说他的整个生命周期都是由他的原始作者来维护
l 编码规范改善软件的可读性,使得软件工程师充分理解新的代码变得非常的快速。
l 如果你要把你的原码作为产品发布,你需要确保他像你的其他产品一样干净并且封装的好。
为了按照规范工作,每个人写软件的时候,都必须遵守编码规范。记住,是每个人!
这本书是反映的是Java Language Specification 中关于java语言编码规范的。在这里要着重对Peter king ,Patrick Naughton,Mike DeMoney,Jonni Kanerva,Kathy Walrath,和SCOtt Hommel表示感谢。
这一节列出了本书所用的大部分文件名和后缀。
.java java 源文件后缀
.class java 字节码文件后缀
经常使用的文件名包括以下:
gnumakefile 首选的makefile的名字,我们使用gnumake来build我们的软件。
README 那些专门概述特定文件夹内容的文件的首选的名字
一个文件的各个部分之间应该用空行隔开,并且应该用一个可选的注解来标示每个不同的部分。
文件超过2000行,是非常笨重讨厌(cumbersome)的,应该避免。
至于java 编程的正确格式的示例,请参看18页上的”JAVA source File Example(Java 原码文件示例)”。
每一个Java源码文件都包括一个唯一的public 类或interface。当私有的类和interface 都和这个public 类有关联时,你可以把它们放到这个public 类的源文件中。这个public 类或interface 应当是这个文件的第一个类或interface 。
Java 源文件有以下的顺序:
l 文件开头注解(参见第二页的“Beginning Comments(开头注解)”)
l 声明package 的语句和载入语句。
l 类和interface的声明(参见page 3的“Class and Interface Declarations”)
所有的源文件都应该以一个C语言风格的注解开头。这个注解应该列出类名,版本信息,日期和版权声明:
/*
*Classname
*
*Version information
*
* Date
*
* copyright notice
*
*/
绝大多数java 源文件中的第一非注释行应该是声明包的语句。此后,紧接着是import 语句。例如:
package java.awt;
import java.awt.peer.CanvASPeer;
下面的表格描述了部分的类和接口的声明,他们应该按照表格的顺序。参看“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)中间。其目的是为了代码可读性和可理解性增加。
应该以四个空格为缩进的最小单位,缩进的精确结构没有被详细定义。Tabs必须被精确指定为8个空格(而不是4个)。
应避免行的长度超过80个字符,因为很多的终端和工具都不支持超过80个字符。(译注:个人认为现在一般都支持行超过80个字符,但是由于超过80个字符,一般要滚屏,所以尽量还是不要超过此限制。)
注意:文档中的例子的行长度应该更短,一般不超过70个字符。
当一个表达式不适合一个单行时,依照以下这些一般性的原理来断行:
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;
待译。
免责声明:本站发布的内容(图片、视频和文字)以原创、转载和分享为主,文章观点不代表本网站立场,如果涉及侵权请联系站长邮箱:is@yisu.com进行举报,并提供相关证据,一经查实,将立刻删除涉嫌侵权内容。