〖建议3-1-4〗源程序中关系较为紧密的代码应尽可能相邻。
说明:
这样便于程序阅读和查找。
正例:
iLength=10;
iWidth=5;//矩形的长与宽关系较密切,放在一起。
StrCaption=“Test”;
反例:
iLength=10;
strCaption=“Test”;
iWidth=5;
3.2对齐
【规则3-2-1】禁止使用TAB键,必须使用空格进行缩进。
缩进为4个空格。
说明:
消除不同编辑器对TAB处理的差异,有的代码编辑器可以设置用空格代替TAB键。
【规则3-2-2】程序的分界符‘{’和‘}’应独占一行并且位于同一列,同时与引用它们的语句左对齐。
{}之内的代码块使用缩进规则对齐。
说明:
这样使代码便于阅读,并且方便注释。
dowhile语句和结构的类型化时可以例外,while条件和结构名可与}在同一行。
正例:
voidFunction(intintVar)
{//独占一行并与引用语句左对齐。
while(condition)
{
DoSomething();//与{}缩进4格
}
}
反例:
voidFunction(intintVar){
while(condition){
DoSomething();
}}
【建议3-2-1】相关的赋值语句等号对齐。
正例:
tPDBRes.wHead=0;
tPDBRes.wTail=wMaxNumOfPDB-1;
tPDBRes.wFree=wMaxNumOfPDB;
tPDBRes.wAddress=wPDBAddr;
tPDBRes.wSize=wPDBSize;
3.3空行空格
【规则3-3-1】不同逻辑程序块之间要使用空行分隔。
说明:
空行起着分隔程序段落的作用。
适当的空行可以使程序的布局更加清晰。
正例:
voidHey(void)
{
[Hey实现代码]
}
//空一行
voidAck(void)
{
[Ack实现代码]
}
反例:
voidHey(void)
{
[Hey实现代码]
}
voidAck(void)
{
[Ack实现代码]
}
//两个函数的实现是两个逻辑程序块,应该用空行加以分隔。
【规则3-3-2】一元操作符如“!
”、“~”、“++”、“--”、“*”、“&”等前后不加空格。
“[]”、“.”这类操作符前后不加空格。
正例:
!
bValue
~iValue
++iCount
&fSum
aiNumber[i]=5;
tBox.dWidth
【规则3-3-3】多元运算符和它们的操作数之间至少需要一个空格。
正例:
fValue=fOldValue;
fTotal+fValue
iNumber+=2;
【规则3-3-4】关键字之后要留空格。
说明:
if、for、while等关键字之后应留一个空格再跟左括号‘(’,以突出关键字。
【规则3-3-5】函数名之后不要留空格。
说明:
函数名后紧跟左括号‘(’,以与关键字区别。
【规则3-3-6】‘(’向后紧跟,‘)’、‘,’、‘;’向前紧跟,紧跟处不留空格。
‘,’之后要留空格。
‘;’不是行结束符号时其后要留空格。
正例:
例子中的凵代表空格。
for凵(i凵=凵0;凵i凵<凵MAX_BSC_NUM;凵i++)
{
DoSomething(iWidth,凵iHeight);
}
3.4断行
【规则3-4-1】长表达式(超过120列)要在低优先级操作符处拆分成新行,操作符放在新行之首(以便突出操作符)。
拆分出的新行要进行适当的缩进,使排版整齐。
说明:
条件表达式的续行在第一个条件处对齐。
for循环语句的续行在初始化条件语句处对齐。
函数调用和函数声明的续行在第一个参数处对齐。
赋值语句的续行应在赋值号处对齐。
正例:
if((iFormat==CH_A_Format_M)
&&(iOfficeType==CH_BSC_M))//条件表达式的续行在第一个条件处对齐
{
DoSomething();
}
for(long_initialization_statement;
long_condiction_statement;//for循环语句续行在初始化条件语句处对齐
long_update_statement)
{
DoSomething();
}
//函数声明的续行在第一个参数处对齐
BYTEReportStatusCheckPara(BYTEbytCallNo,
BYTEbytStatusReportNo);
//赋值语句的续行应在赋值号处对齐
fltTotalBill=fltTotalBill+fltarrCustomerPurchases[intID]
+fltSalesTax(fltarrCustomerPurchases[intID]);
【规则3-4-2】函数声明时,类型与名称不允许分行书写。
正例:
doubleCalcArea(doubledblWidth,doubledblHeight);
反例:
double
CalcArea(doubledblWidth,doubledblHeight);
4注释
注释有助于理解代码,有效的注释是指在代码的功能、意图层次上进行注释,提供有用、额外的信息,而不是代码表面意义的简单重复。
【规则4-1】类、方法、属性的注释采用XML文档格式注释。
文件头部、代码间多行注释为“/*…*/”,单行注释采用“//…”。
正例:
publicclassSample
{
//数据成员(单行注释)
privateintmProperty1;
///(XML注释)
///示例属性
///
publicintProperty1
{
get
{
returnmProperty1;
}
/*set(多行注释)
{
mProperty1=value;
}*/
}
【规则4-2】注释符与注释内容之间要用一个空格进行分隔。
正例:
/*注释内容*/
//注释内容
反例:
/*注释内容*/
//注释内容
【规则4-3】类、接口头部应进行XML注释。
说明:
注释必须列出:
类、接口编号、名称、内容摘要等。
类编号由功能模块编号和类名两部分组成,中间用“_”隔开,功能模块编号使用该类所在
的功能模块的编号,类名用类的名称。
例如:
M01_Employee。
正例:
///
///类编号:
///类名称:
///内容摘要:
///
【规则4-4】公共方法前面应进行XML注释。
说明:
注释必须列出:
主要功能、参数类型、输入参数、返回值、调用的前置条件和后置条件、异常说明、关键算法、可见性决策等。
【规则4-5】包含在{}中代码块的结束处应加注释,便于阅读。
特别是多分支、多重嵌套的条件语句或循环语句。
说明:
此时注释可以用英文,方便查找对应的语句。
正例:
voidMain()
{
if(…)
{
…
while(…)
{
…
}/*endofwhile(…)*///指明该条while语句结束
…
}/*endofif(…)*///指明是哪条语句结束
}/*endofvoidmain()*///指明函数的结束
【规则4-6】注释应与其描述的代码相近,对代码的注释应放在其上方或右方(对单条语句的注释)相邻位置,不可放在下面,如放于上方则需与其上面的代码用空行隔开。
说明:
在使用缩写时或之前,应对缩写进行必要的说明。
避免在代码行的末尾添加注释;行尾注释使代码更难阅读。
不过在批注变量声明时,行尾注释是合适的;在这种情况下,将所有行尾注释在公共制表位处对齐。
正例:
如下书写比较结构清晰
/*获得子系统索引*/
iSubSysIndex=aData[iIndex].iSysIndex;
/*代码段1注释*/
[代码段1]
/*代码段2注释*/
[代码段2]
反例1:
如下例子注释与描述的代码相隔太远。
/*获得子系统索引*/
iSubSysIndex=aData[iIndex].iSysIndex;
反例2:
如下例子注释不应放在所描述的代码下面。
iSubSysIndex=aData[iIndex].iSysIndex;
/*获得子系统索引*/
反例3:
如下例子,显得代码与注释过于紧凑。
/*代码段1注释*/
[代码段1]
/*代码段2注释*/
[代码段2]
【规则4-7】注释与所描述内容进行同样的缩排。
说明:
可使程序排版整齐,并方便注释的阅读与理解。
正例:
如下注释结构比较清晰
intDoSomething(void)
{
/*代码段1注释*/
[代码段1]
/*代码段2注释*/
[代码段2]
}
反例:
如下例子,排版不整齐,阅读不方便;
intDoSomething(void)
{
/*代码段1注释*/
[代码段1]
/*代码段2注释*/
[代码段2]
}
【规则4-8】对分支语句(条件分支、循环语句等)必须编写注释。
说明:
这些语句往往是程序实现某一特殊功能的关键,对于维护人员来说,良好的注释有助于更好的理解程序,有时甚至优于看设计文档。
〖建议4-1〗通过对函数或过程、变量、结构等正确的命名以及合理地组织代码结构,使代码成为自注释的。
说明:
清晰准确的函数、变量命名,可增加代码的可读性。
〖建议4-2〗尽量避免在注释中使用缩写,特别是不常用缩写。
说明:
在使用缩写时,应对缩写进行必要的说明。
5命名规则
好的命名规则能极大地增加可读性和可维护性。
同时,对于一个有上百个人共同完成的大项目来说,统一命名约定也是一项必不可少的内容。
本章对程序中的所有标识符(包括命名空间、变量名、常量名、控件名、参数名、属性名、方法名、类名、接口等)的命名做出约定。
三种命名规范说明:
Pascal规范:
第1个字符大写,目标名中的每个单词的第1个字母也大写,比如InvoiceNumber或者PrintInvoice。
其他的所有字符都小写。
Camel规范:
第1个字符不大写,但目标名中的每个单词的第1个字母大写,比如,invoiceNumber。
其他的所有字符都小写。
匈牙利规范:
在目标名中加入表示类型的前缀,前缀小写,如strName。
【规则5-1】标识符要采用英文单词或其组合,便于记忆和阅读,切忌使用汉语拼音来命名。
说明:
标识符应当直观且可以拼读,可望文知义,避免使人产生误解。
程序中的英文单词一般不要太复杂,用词应当准确。
【规则5-2】标识符只能由26个英文字母,10个数字,及下划线的一个子集来组成,并严格禁止使用连续的下划线,下划线也不能出现在标识符头或结尾(预编译开关和利用工具生成的代码除外);数字也不能出现在标识符的头部。
说明:
这样做的目的是为了使程序易读。
因为variable_name和variable__name很难区分,下划线符号‘_’若出现在标识符头或结尾,容易与不带下划线‘_’的标识符混淆。
【规则5-3】标识符的命名应当符合“min-length&&max-information”原则。
说明:
较短的单词可通过去掉“元音”形成缩写,较长的单词可取单词的头几个字母形成缩写,一些单词有大家公认的缩写,常用单词的缩写必须统一。
协议中的单词的缩写与协议保持一致。
对于某个系统使用的专用缩写应该在某处做统一说明。
在使用缩写时,应该按着专业术语的要求大小写,例如,System.IO,而不是System.Io。
正例:
如下单词的缩写能够被大家认可:
temp可缩写为tmp;
flag可缩写为flg;
statistic可缩写为stat;
increment可缩写为inc;
message可缩写为msg;
规定的常用缩写如下:
常用词
缩写
Argument
Arg
Buffer
Buf
Clear
Clr
Clock
Clk
Compare
Cmp
Configuration
Cfg
Context
Ctx
Delay
Dly
Device
Dev
Disable
Dis
Display
Disp
Enable
En
Error
Err
Function
Fnct
Hexadecimal
Hex
HighPriorityTask
HPT
I/OSystem
IOS
Initialize
Init
Mailbox
Mbox
Manager
Mgr
Maximum
Max
Message
Msg
Minimum
Min
Multiplex
Mux
OperatingSystem
OS
Overflow
Ovf
Parameter
Param
Pointer
Ptr
Previous
Prev
Priority
Prio
Read
Rd
Ready
Rdy
Register
Reg
Schedule
Sched
Semaphore
Sem
Stack
Stk
Synchronize
Sync
Timer
Tmr
Trigger
Trig
Write
Wr
【规则5-4】采用应用领域相关的术语来命名。
说明:
软件开发人员应注意软件用户的一些约定术语,不应当随意的创造术语,这会降低软件的易用性。
【规则5-5】程序中不要出现仅靠大小写区分的相似的标识符。
【规则5-6】用正确的反义词组命名具有互斥意义的变量或相反动作的函数等。
说明:
下面是一些在软件中常用的反义词组。
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
【规则5-7】常量名都要使用大写字母,用下划线‘_’分割单词。
正例:
如DISP_BUF_SIZE、MIN_VALUE、MAX_VALUE等等。
【规则5-8】一般变量名不得取单个字符(如i、j、k等)作为变量名,局部循环变量除外。
说明:
变量,尤其是局部变量,如果用单个字符表示,很容易出错(如l误写成1),而编译时又检查不出,则有可能增加排错时间。
过长的变量名会增加工作量,会使程序的逻辑流程变得模糊,给修改带来困难,所以应当选择精炼、意义明确的名字,才能简化程序语句,改善对程序功能的理解。
【规则5-9】类方法的局部变量命名采用Camel规范或匈牙利规范。
说明:
常用变量类型前缀列表如下:
int:
int
flt:
float
dbl:
double
chr:
char
lng:
long
sht:
short
bl:
bool
ush:
ushort
uln:
ulong
arr:
array
str:
string
【规则5-10】类成员变量名应由前缀+变量名主体组成,变量名的主体应当使用“名词”或者“形容词+名词”,且首字母必须大写。
说明:
前缀为m或_,一般是对应属性的私有变量是m开头的,对应聚合组合依赖等关系的是_开头。
正例:
privatestaticstringmPersonName;
privatestaticstring_PersonName;
privatestringmPersonName;
privatestring_PersonName;
【规则5-11】控件命名应采用完整的英文描述符命名,名字的前缀是控件类型名缩写,符合匈牙利命名规范。
说明:
控件
缩写
Label
lbl
TextBox
txt
CheckBox
chk
Button
btn
ListBox
lst
DropDownList
ddlst
LinkButton
lbtn
ImageButton
ibtn
RadioButtonList
rblst
CheckBoxList
chlst
DataGrid
dg
DataList
dl
HyperLink
hlnk
Repeater
rp
Image
img
等等
【规则5-12】Enum类型和值命名采用Pascal规范,不要在Enum类型名称上使用Enum后缀。
【规则5-13】类方法的参数名命名采用Camel规范或匈牙利规范