【规则1-1-4】包名以com.kotei.项目名.机能名,根据项目情况分类,一个包集中放一个机能所有类,或者一个包里集中放一组控件。
说明:
关于自身包名的定义,将所有UI可以定义为一个包,或所有的Activity集中放一个包。
或者根据机能名定义一个包。
正例:
packagecom.kotei.Aster.Activity//将所有Activity集中放到一个包里。
packagecom.kotei.Aster.Phone//将phone这个进程单独作为一个包,里面分Activity。
〖建议1-1-1〗源程序中关系较为紧密的代码应尽可能相邻。
说明:
这样便于程序阅读和查找。
正例:
length=10;
width=5;//矩形的长与宽关系较密切,放在一起。
strCaption=“Test”;
反例:
length=10;
strCaption=“Test”;
width=5;
1.2对齐
【规则1-2-1】一般禁止使用制表符,必须使用空格进行缩排。
缩进为4个空格。
说明:
对于利用Eclipse等编程工具的,可以设置TAB键为4个空格代替。
消除不同编辑器对制表符处理的差异。
【规则1-2-2】程序的分界符‘{’和‘}’应独占一行,‘}’同时与引用它们的语句左对齐。
{}之内的代码块使用缩进规则对齐。
说明:
这样使代码便于阅读,并且方便注释。
do…while语句可以例外,while条件可与}在同一行。
正例:
voidfunction(intvar)
{
while(condition)
{
doSomething();//与{}缩进4格
}//与引用它们的模块左对齐
}
反例:
voidfunction(intvar)
{
while(condition)
{
doSomething();
}
}
【规则1-2-3】多维的数组如果在定义时初始化,按照数组的矩阵结构分行书写。
正例:
int[][]number=
{
{1,1,1},
{2,4,8},
{3,9,27},
{4,16,64}
};
【建议1-2-1】相关的赋值语句等号对齐。
正例:
width=50;
length=20;
height=40;
1.3空行空格
【规则1-3-1】不同逻辑程序块之间要使用空行分隔。
说明:
空行起着分隔程序段落的作用。
适当的空行可以使程序的布局更加清晰。
下列情况应该总是使用空行:
●一个源文件的两个片段(section)之间
●类声明和接口声明之间
●常量声明区域之后
●方法声明之前
●方法内的局部变量和方法的第一条语句之间
●一个方法内的两个逻辑段之间,用以提高可读性
正例:
voiddoSomething()
{
Connectioncon=null;//数据库连接
BooleanreturnParameter=false;//返回
//空一行
//if代码的注释
if(reconsign==null)
{
returnfalse;
}
}
反例:
voiddoSomething()
{
Connectioncon=null;//数据库连接
BooleanreturnParameter=false;//返回
//if代码的注释
if(reconsign==null)
returnfalse;
}
【规则1-3-2】一元操作符如“++”、“--”、“!
”、“~”、(类型)等前后不加空格。
“[]”“.”这类操作符前后不加空格。
正例:
!
value
~value
++count
number[i]=5;
box.getWidth();
【规则1-3-3】多元运算符和它们的操作数之间至少需要一个空格。
说明:
空格的多少根据上下文调整。
正例:
value=oldValue;
total+value;
number+=2;
【规则1-3-4】方法名之后不要留空格。
说明:
方法名后紧跟左括号‘(’。
【规则1-3-5】‘(’向后紧跟,‘)’、‘,’、‘;’向前紧跟,紧跟处不留空格。
‘,’之后要留空格。
‘;’不是行结束符号时其后要留空格。
正例:
例子中的凵代表空格。
for(i凵=凵0;凵i凵<凵MAX_BSC_NUM;凵i++)
{
doSomething(width,凵height);
}
正例:
if(flg==true)
{
Length=20;
Height=40;
}
反例:
if(flg==false)
{
Length=20;
Height=40;
}
1.4断行
【规则1-4-1】长表达式(超过80列)要在低优先级操作符处拆分成新行,操作符放在新行之首(以便突出操作符)。
拆分出的新行要进行适当的缩进,使排版整齐。
说明:
断行方法:
1.在逗号后断行
2.在操作符前断行
3.在低优先级操作符处断行
对齐方法:
1.将新行与同一级别的先前行的表达式的起始端对齐。
2.条件表达式的续行在第一个条件处对齐。
3.for循环语句的续行在初始化条件语句处对齐。
4.函数调用和函数声明的续行在第一个参数处对齐。
5.赋值语句的续行应在赋值号处对齐。
6.如果上述规则导致代码排列混乱或代码左边界少于两个缩进,可用两倍缩进替代。
下面是一些断行方法调用的示例:
正例:
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个空格符替代。
//传统的缩排方法,第二行与第一行的括号对齐。
正例:
voidsomeMethod(intanArg,ObjectanotherArg,StringyetAnotherArg,
ObjectandStillAnother)
{
...//你代码的位置
}
//由8个空格符来替代与括号对齐的方法,以避免第二行、第三行出现太多的空格符
正例:
privatestaticsynchronizedhorkingLongMethodName(intanArg,
ObjectanotherArg,StringyetAnotherArg,
ObjectandStillAnother)
{
...//你代码的位置
}
对于if语句的行封装通常使用8空格规则,因为传统的4空格缩排方式使得有些语句容易被忽略掉,使if语句体难以理解。
例如:
反例:
//不允许使用下面的缩进方法
if((condition1&&condition2)
||(condition3&&condition4)
||!
(condition5&&condition6))
{//不好的缩进
doSomethingAboutIt();//这样对齐的缩进方式很容易让阅读的人忽略掉这一行
}
正例:
//宜采用下面的缩进方法(分成三行的情况)
if((condition1&&condition2)
|(condition3&&condition4)
||!
(condition5&&condition6))
{
doSomethingAboutIt();
}
//或使用下面的缩进方法(分成二行的情况)
正例:
if((condition1&&condition2)||(condition3&&condition4)
||!
(condition5&&condition6))
{
doSomethingAboutIt();
}
对于三重表达式,有三种方式可以对它进行换行缩排:
正例:
//单行的情况
alpha=(aLongBooleanExpression)?
beta:
gamma;
//分成两行的情况,第二行的冒号与第一行的问号对齐。
alpha=(aLongBooleanExpression)?
beta
:
gamma;
//分成三行的情况,第二行的问号和第三行的冒号都与第一行的括号对齐
alpha=(aLongBooleanExpression)
?
beta
:
gamma;
【规则1-4-2】方法声明时,修饰符、类型与名称不允许分行书写。
正例:
publicstaticdoublecalculateArea(doublewidth,doubleheight);
反例:
publicstaticdouble
calculateArea(doublewidth,doubleheight);
2注释
注释有助于理解代码,有效的注释是指在代码的功能、意图层次上进行注释,提供有用、额外的信息,而不是代码表面意义的简单重复。
Java程序有两类注释:
实现注释,文档注释。
2.1实现注释
实现注释是那些在C++中见过的,使用/*…*/和//界定的注释。
实现注释有4种实现注释的风格:
Ø块注释(BlockComments)
块注释被置于每个文件的开始处以及每个方法之前。
它们也可以被用于其他地方,比如方法的内部。
在功能和方法内部的块注释应该和它们所描述的代码具有一样的缩进格式。
Ø单行注释(single-lineComments)
短注释可以显示一行内,并与其后的代码具有一样的缩进层级。
如果一个注释不能在一行内写完,就该块注释(参见“块注释”)。
单行注释之前应该有一个空行。
以下是一个Java代码中单行注释的例子:
if(condition)
{
/*Handlethecondition.*/
……
}
Ø尾端(trailing)
极短的注释可以与它们所要描述的代码位于同一行,但是应该有足够的空白来分开代码和注释。
以下是一个Java代码中单行注释的例子:
if(a==2)
{
returnTRUE;/*specialcase*/
}
Ø行末(end-of-line)。
注释界定符“//”,可以注释掉整行或者一行中的一部分。
它一般不用于连续多行的注释文本;然而,它可以用来注释掉多行的代码段。
【规则2-1-1】块注释之首应该有一个空行,用于把块注释和代码分割开来
正例:
/*
*Hereisablockcomment.
*/
反例:
/*Hereisablockcomment.
*/
【规则2-1-2】注释符与注释内容之间要用一个空格进行分隔。
正例:
/*注释内容*/
//注释内容
反例:
/*注释内容*/
//注释内容
【规则2-1-3】注释应与其描述的代码相近,对代码的多行注释应放在其上方,空出一行,单行的情况可以放在代码的上方或者右方(对单条语句的注释)相邻位置,不可放在下面。
说明:
在使用缩写时或之前,应对缩写进行必要的说明。
避免在代码行的末尾添加注释;行尾注释使代码更难阅读。
不过在批注变量声明时,行尾注释是合适的;在这种情况下,将所有行尾注释在公共制表位处对齐。
正例:
如下书写结构比较清晰
//获得子系统索引
subSysIndex=data.getSysIndex;
//代码段1注释
[代码段1]
/*代码段2注释*/
[代码段2]
反例1:
如下例子注释与描述的代码相隔太远。
/*获得子系统索引*/
subSysIndex=subSys.getSysIndex();
反例2:
如下例子注释不应放在所描述的代码下面。
subSysIndex=subSys.getSysIndex();
/*获得子系统索引*/
反例3:
如下例子,显得代码与注释过于紧凑。
/*代码段1注释*/
[代码段1]
/*代码段2注释*/
[代码段2]
【规则2-1-4】单行注释与所描述内容进行同样的缩进。
说明:
这样可使程序排版整齐,并方便注释的阅读与理解。
正例:
如下注释结构比较清晰
intdoSomething()
{
/*代码段1注释*/
[代码段1]
/*代码段2注释*/
[代码段2]
}
反例:
如下例子,排版不整齐,阅读不方便;
intdoSomething()
{
/*代码段1注释*/
[代码段1]
/*代码段2注释*/
[代码段2]
}
〖规则2-1-5〗包含在{}中代码块的结束处要加注释,便于阅读。
特别是多分支、多重嵌套的条件语句或循环语句。
说明:
此时注释用英文,方便查找对应的语句。
正例:
voiddoSomething()
{
if(do
{
…
while(g(
{
…
}//endofwhile(ile(别是多指明该条while语句结束
…
}//endofif(e((e分支、多重嵌套的条件语指明是哪条语句结束
}//endofvoidmain()//指明函数的结束
〖规则2-1-6〗对分支语句(条件分支、循环语句等)必须编写注释。
说明:
这些语句往往是程序实现某一特殊功能的关键,对于维护人员来说,良好的注释有助于更好的理解程序,有时甚至优于看设计文档。
2.2文档注释
文档注释(被称为“doccomments”)是Java独有的,并由/**…*/界定,注释内容里包含标签。
文档注释可以通过javadoc工具转换成HTML文件。
实现注释用以注释代码或或者实现细节。
文档注释从实现自由(implemtentation-free)的角度描述代码的规范。
它可以被那些手头没有源码的开发人员读懂。
【规则2-2-1】注释使用英文注释,不用其他语言。
与doc有关的标准英文单词标签保留。
说明:
文档型注释描述了Java类(Javaclasses),接口(interfaces),构造函数(constructors)、方法(methods)和域(fields)。
每一个文档注释都包含在/**…*/分隔符中,每一个类(class)、接口(interface)或成员(member)都有一个注释。
这些注释应该只出现在声明(declaration)前。
标签
用处
用途
类编号,类名
类、接口、方法
说明类或方法的用途,内容概要。
参照规则2-2-2
@deprecated(可选)
类、方法
说明该类的应用程序编程接口(API)已被废弃,因此应不再使用。
@paramname参数名的描述
方法
说明传递给一个方法的参数,其中包括参数的类型/类和用法。
每个参数各有一个标记。
@return方法返回值的描述
方法
若方法有返回值,对该返回值进行说明。
应说明返回值的类型/类和可能的用途。
@author作者的名称
类、接口
说明特定某一段程序代码的作者。
每一个作者各有一个标记。
@version版本号
类、接口
说明特定一段代码的版本信息。
@exceptionnamedescription(可选)
方法
说明由方法发出的异常。
一个异常采用一个标记,并要给出异常的完整类名。
@since(可选)
类、方法
例如:
sinceJDK1.1:
说明自从有JDK1.1以来,该项已存在了多长时间。
@see类名(可选)
类、接口、方法、字段
在文档中生成指向特定类的超文本链接。
可以并且应该采用完全合法的类名。
@seeClassName#memberfunctionName
(可选)
类、接口、方法、字段
在文档中生成指向特定方法的超文本链接。
可以并且应该采用完全合法的类名。
@history变更履历
类、接口、方法、
格式为:
变更人姓名拼音,变更时间(yyyy/mm/dd),变更内容。
变更的版本号写在@version里,参照正例。
正例:
/**
*类编号:
*类名称:
*内容摘要:
//说明主要功能。
*@deprecated
*@paramnameStringname:
thenameofdevice//类型,名称,冒号后写参数说明*intnumber:
thenumberofdevice//多个参数分行书写
*@returnBooleantrue:
success//返回类型返回状态,说明
*false:
failure
*@authorzhaozhengoddc1-1//姓名,所属部门
*@version1.0//新规时1.0,变更后累加。
*@exceptionnameNullPointerException//声明异常的类型。
*@sinceJDK1.5//声明从哪个版本开始
*@seeInputStream//声明类名
*@historyzhaozheng,2013/11/05,new//用逗号分隔,new是新规
*@historyzhaozheng,2013/11/06,修改判断条件//变更不是new,