【规则5-1-5】源程序中关系较为紧密的代码应尽可能相邻。
【规则5-1-6】不同逻辑程序块之间要使用一个空行分隔。
【建议5-1-7】java代码缩进用tab,不用空格,一个tab定义为四个空格。
非java代可以使用TAB键,也可以使用空格进行缩进。
缩进为4个空格。
说明:
这样便于程序阅读和查找。
5.2.对齐
说明:
这样使代码便于阅读,并且方便注释。
正例:
voidFunction(intiVar)
{
while(condition)
{
DoSomething();//缩进一个tab,4格
}
}
反例:
voidFunction(intiVar)
{
while(condition)
{
DoSomething();
}
}
说明:
消除不同编辑器对TAB处理的差异,有的代码编辑器可以设置用空格代替TAB键。
5.3.空行空格
说明:
空行起着分隔程序段落的作用。
适当的空行可以使程序的布局更加清晰。
正例:
【规则5-3-2】一元操作符如“!
”、“~”、“++”、“--”、“*”、“&”等前后不加空格。
“[]”、“.”这类操作符前后不加空格。
【规则5-3-3】多元运算符和它们的操作数之间留一个空格。
【规则5-3-4】关键字之后要留空格。
【规则5-3-5】函数名之后不要留空格。
【规则5-3-6】‘(’向后紧跟,‘)’、‘,’、‘;’向前紧跟,紧跟处不留空格。
‘,’之后要留空格。
‘;’不是行结束符号时其后要留空格。
【规则5-3-7】xml布局文件末尾留有一个单独的空行
voidHey(void)
{
[Hey实现代码]
}
//空一行
voidAck(void)
{
[Ack实现代码]
}
反例:
voidHey(void)
{
[Hey实现代码]
}
voidAck(void)
{
[Ack实现代码]
}
//两个函数的实现是两个逻辑程序块,应该用空行加以分隔。
正例:
!
bValue
~iValue
++iCount
&fSum
aiNumber[i]=5;
tBox.dWidth
正例:
fValue=fOldValue;
fTotal+fValue;
iNumber+=2;
说明:
if、for、while等关键字之后应留一个空格再跟左括号‘(’,以突出关键字。
【规则5-3-7】注释符与注释内容之间要用一个空格进行分隔。
【规则5-4-1】长表达式(超过120列)要在低优先级操作符处拆分成新行,操作符放在新行之首(以便突出操作符)。
拆分出的新行要进行适当的缩进,使排版整齐。
【规则5-4-2】函数声明时,类型与名称不允许分行书写。
说明:
函数名后紧跟左括号‘(’,以与关键字区别。
正例:
例子中的凵代表空格。
for凵(i凵=凵0;凵i凵<凵MAX_BSC_NUM;凵i++)
{
DoSomething(iWidth,凵iHeight);
}
正例:
/*注释内容*/
//注释内容
反例:
/*注释内容*/
//注释内容
5.4.断行
正例:
if((iFormat==CH_A_Format_M)&&(iOfficeType==CH_BSC_M))//条件表达式的续行在第一个条件处对齐
{
DoSomething();
}
//函数声明的续行在第一个参数处对齐
BYTEReportStatusCheckPara(BYTEucCallNo,
BYTEucStatusReportNo);
//赋值语句的续行应在赋值号处对齐
fTotalBill=fTotalBill+faCustomerPurchases[iID]
+fSalesTax(faCustomerPurchases[iID]);
正例:
doubleCalcArea(doubledWidth,doubledHeight);
反例:
double
CalcArea(doubledWidth,doubledHeight);
6.注释
注释有助于理解代码,有效的注释是指在代码的功能、意图层次上进行注释,提供有用、额外的信息,而不是代码表面意义的简单重复。
【规则6-1】类、方法、属性的注释采用Javadoc格式注释。
代码间多行注释为“/*…*/”,单行注释采用“//…”。
不要再方法内部使用javadoc 形式的注释“/**……**/”
正例:
/**
*该类所实现的功能简要描述
*
*@authorauthorname
*
*/
publicclassSample
{
//成员变量
privateintmProperty1;
/**
*获取属性值
*/
publicintgetProperty1()
{
returnm_iProperty1;
}
/**
*手动登录
*@paramusername
*@parampwd
*@return登录成功则返回true,否则返回false
*/
publicbooleanloginManual(Stringusername,Stringpwd)
{
returntrue;
}
}
【规则6-2】一般情况下,源程序有效注释量必须在20%以上。
说明:
注释的原则是有助于对程序的阅读理解,注释不宜太多也不能太少,注释语言必须准确、易懂、简洁。
有效的注释是指在代码的功能、意图层次上进行注释,提供有用、额外的信息。
注释使用中文,保证代码和注释的一致性。
修改代码同时修改相应的注释,不再有用的注释要删除。
注释应与其描述的代码相近,对代码的注释应放在其上方或右方(对单条语句的注释)相邻位置,不可放在下面,如放于上方则需与其上面的代码用空行隔开。
【规则6-3】注释应与其描述的代码相近,对代码的注释应放在其上方或右方(对单条语句的注释)相邻位置,不可放在下面,如放于上方则需与其上面的代码用空行隔开。
说明:
在使用缩写时或之前,应对缩写进行必要的说明。
正例:
如下书写比较结构清晰
/*获得子系统索引*/
subSysIndex=aData[index].SysIndex;
/*代码段1注释*/
[代码段1]
/*代码段2注释*/
[代码段2]
反例1:
如下例子注释与描述的代码相隔太远。
/*获得子系统索引*/
iSubSysIndex=aData[iIndex].iSysIndex;
反例2:
如下例子注释不应放在所描述的代码下面。
iSubSysIndex=aData[iIndex].iSysIndex;
/*获得子系统索引*/
反例3:
如下例子,显得代码与注释过于紧凑。
/*代码段1注释*/
[代码段1]
/*代码段2注释*/
[代码段2]
反例4:
如下例子,排版不整齐,阅读不方便。
intDoSomething(void){
/*代码段1注释*/
[代码段1]
/*代码段2注释*/
[代码段2]
}
【规则6-4】对分支语句(条件分支、循环语句等)必须编写注释。
说明:
这些语句往往是程序实现某一特殊功能的关键,对于维护人员来说,良好的注释有助于更好的理解程序,有时甚至优于看设计文档。
【建议6-5】通过对函数或过程、变量、结构等正确的命名以及合理地组织代码结构,使代码成为自注释的。
【建议6-6】修改代码应该在修改开始处加注释,格式如下,包含修改原因,如果是BUG附上BUGID,修改时间跟修改人的姓名。
//修改原因[BUGID]-20150819byWho
说明:
清晰准确的函数、变量命名,可增加代码的可读性,减少不必要的注释。
7.命名规则
好的命名规则能极大地增加可读性和可维护性。
同时,对于一个有上百个人共同完成的大项目来说,统一命名约定也是一项必不可少的内容。
本章对程序中的所有标识符(包括命名空间、变量名、常量名、控件名、参数名、属性名、方法名、类名、接口等)的命名做出约定。
【规则7-1】标识符要采用英文单词或其组合,便于记忆和阅读,切忌使用汉语拼音来命名。
【规则7-2】标识符只能由26个英文字母,10个数字,及下划线的一个子集来组成,并严格禁止使用连续的下划线,下划线也不能出现在标识符头或结尾(预编译开关除外)。
【规则7-3】标识符的命名应当符合“min-length&&max-information”原则。
【规则7-4】采用应用领域相关的术语来命名。
【规则7-6】用正确的反义词组命名具有互斥意义的变量或相反动作的函数等。
说明:
标识符应当直观且可以拼读,可望文知义,避免使人产生误解。
程序中的英文单词一般不要太复杂,用词应当准确。
说明:
这样做的目的是为了使程序易读。
因为variable_name和variable__name很难区分,下划线符号‘_’若出现在标识符头或结尾,容易与不带下划线‘_’的标识符混淆。
说明:
较短的单词可通过去掉“元音”形成缩写,较长的单词可取单词的头几个字母形成缩写,一些单词有大家公认的缩写,常用单词的缩写必须统一。
协议中的单词的缩写与协议保持一致。
对于某个系统使用的专用缩写应该在某处做统一说明。
正例:
如下单词的缩写能够被大家认可:
temp可缩写为tmp;
statistic可缩写为stat;
increment可缩写为inc;
message可缩写为msg;
说明:
软件开发人员应注意软件用户的一些约定术语,不应当随意的创造术语,这会降低软件的易用性。
说明:
下面是一些在软件中常用的反义词组。
add/remove;begin/end;create/destroy;insert/delete;
first/last;get/release;increment/decrement;put/get;
add/delete;lock/unlock;open/close;min/max;
old/new;start/stop;next/previous;source/target;
show/hide;send/receive;source/destination;cut/paste;
up/down
【规则7-7】常量名都要使用大写字母,用下划线‘_’分割单词。
【规则7-8】一般变量名不得取单个字符(如i、j、k等)作为变量名,局部循环变量除外。
【规则7-9】使用一致的前缀来区分变量的作用域。
【规则7-10】完整的变量名应由前缀+变量名主体组成,变量名的主体应当使用“名词”或者“形容词+名词”,且首字母必须小写。
正例:
如DISP_BUF_SIZE、MIN_VALUE、MAX_VALUE等等。
说明:
变量,尤其是局部变量,如果用单个字符表示,很容易出错(如l误写成1),而编译时又检查不出,则有可能增加排错时间。
过长的变量名会增加工作量,会使程序的逻辑流程变得模糊,给修改带来困难,所以应当选择精炼、意义明确的名字,才能简化程序语句,改善对程序功能的理解。
建议:
变量活动范围前缀规范如下:
m:
类的成员变量(属性所对应的变量),bean除外。
空:
局部变量不加范围前缀
建议:
控件对象命采用控件缩写+属性名字的形式展现:
例子:
privateTextViewtvTitle;
说明:
各种前缀字符可能组合使用,在这种情况下,各前缀顺序为:
变量作用域前缀、变量类型前缀。
正例:
publicclassHello
{
privatestringmStrName;
publicstringgetName()
{
returnmStrName;
}
}
说明:
控件
缩写
Button
btn
ImageButton
ibtn
ImageView
iv
ProgressBar
pbar
ScrollView
sclv
RelativeLayout
rlyt
TableLayout
tlyt
FrameLayout
flyt
RadioButton
rbtn
TextView
tv
ListView
lstv
EditText
et
CheckBox
cbx
LinearLayout
llyt
AbsoluteLayout
alyt
【规则7-11】控件命名应采用完整的英文描述符命名,名字的前缀是控件类型名缩写。
【规则7-12】方法名用大写字母开头的单词组合而成,且应当使用“动词”或者“动词+名词”(动宾词组)。
【规则7-13】类名采用大小写结合的方法,构成类名的每个单词的首字母的首字母也必须大写。
在构成类名的单词之间不用下划线。
【规则7-14】接口命名在名字前加上“I”前缀,其它和类命名规范相同。
说明:
方法名力求清晰、明了,通过方法名就能够判断方法的主要功能。
方法名中不同意义字段之间不要用下划线连接,而要把每个字段的首字母大写以示区分。
函数命名采用大小写字母结合的形式,但专有名词不受限制。
说明:
1. 名字应该能够标识事物的特性。
2. 名字尽量不使用缩写,除非它是众所周知的。
3. 名字可以有两个或三个单词组成,但通常不应多于三个。
4.在名字中,所有单词第一个字母大写。
Android相关类的命名
●每个单词首字母大写,驼峰式命名。
●以类的类型为后缀。
类型
后缀
示例
Activity
Activity
MainActivity.java
Service
Service
AppUpgradeService.java
BroadCastReceiver
Receiver
CardScanReceiver
布局资源文件命名规范
●具体类布局资源文件:
类名_【*功能描述】。
例如:
dishact.xml、dishact_category.xml、dishact_category_listitem.xml
●公共布局资源文件:
【+资源功能名称】。
例如:
lstitem.xml、lstitem_oneicon.xml、lstitem_twoicon.xml
图片命名规范
●具体类布局中的图片:
类名_【*控件名】_图片描述。
例如:
mainact_bg.png、mainact_btnleft_category.png
●公用图片:
【*控件名】_图片描述。
例如:
btn_save.png
组件id命名
●组件id的命名,类名_组件简写_功能描述。
例如:
主界面中用于显示用户名的标签:
mainact_tv_name
资源文件中的字符串命名
●具体类的资源字符串:
类名_功能描述。
例如:
账号
●公用资源字符串:
直接用相应的英文命名就可以了。
例如:
确定。
欢迎使用
字符串节点按照具体类来分块组织,每个类的字符串块的第一行之前用xml注释。
共用字符串块放到xml文件最开头。
—公共资源-->
快乐·购物
--主界面-->
优惠券
我的订单
--欢迎界面-->
助手
8.声明
【规则8-1】一行只声明一个变量。
【规则8-2】一个变量有且只有一个功能,不能把一个变量用于多种用途。
正例:
intlevel;
intsize;
反例:
intlevel,size;
说明:
一个变量只用来表示一个特定功能,不能把一个变量作多种用途,即同一变量取值不同时,其代表的意义也不同。
9.表达式与语句
表达式是语句的一部分,它们是不可分割的。
表达式和语句虽然看起来比较简单,但使用时隐患比较多。
本章归纳了正确使用表达式和if、for、while、switch等基本语句的一些规则与建议。
【规则9-1】一条语句只完成一个功能。
说明:
复杂的语句阅读起来,难于理解,并容易隐含错误。
变量定义时,一行只定义一个变量。
正例:
inthelp;
intbase;
intresult;
help=base;
result=help+GetValue(base);
反例:
intbase,result;//一行定义多个变量
result=base+GetValue(base);//一条语句实现多个功能,base有两种用途。
【规则9-2】在表达式中使用括号,使表达式的运算顺序更清晰。