软件设计更多地是一种工程,而不是一种个人艺术。如果不统一编程规范,最终写出的程序,其可读性将较差,这不仅给代码的理解带来障碍,增加维护阶段的工作量,同时不规范的代码隐含错误的可能性也比较大。 分析表明,编码阶段产生的错误当中,语法错误大概占20%左右,而由于未严格检查软件逻辑导致的错误、函数(模块)之间接口错误及由于代码可理解度低导致优化维护阶段对代码的错误修改引起的错误则占了一半以上。可见,提高软件质量必须降低编码阶段的错误率。如何有效降低编码阶段的错误呢?这需要制定详细的软件编程规范,并培训每一位程序员,最终的结果可以把编码阶段的错误降至10%左右,同时也降低了程序的测试费用,效果相当显著。 本文从代码的可维护性(可读性、可理解性、可修改性)、代码逻辑与效率、函数(模块)接口、可测试性四个方面阐述了软件编程规范,规范分成规则和建议两种,其中规则部分为强制执行项目,而建议部分则不作强制,可根据习惯取舍。 1.排版
规则1
程序块使用缩进方式,函数和标号使用空格缩进,程序段混合使用TAB和空格缩进。缩进的目的是使程序结构清晰,便于阅读和理解。
<TAB>默认宽度应为8个空格,由于Word中<TAB>为4个空格,为示范清晰,此处用2个<TAB>代替(下同)。
例如:
MOV R1, #00H
MOV R2, #00H
MOV PMR, #PMRNORMAL
MOV DPS, #FLAGDPTR
MOV DPTR, #ADDREEPROM
read1kloop:
read1kpage:
INC R1
MOVX A, @DPTR
MOV SBUF, A
JNB TI, $
CLR TI
INC DPTR
CJNE R1, #20H, read1kpage
INC R2
MOV R1, #00H
CPL WDI
CJNE R2, #20H, read1kloop ;END OF EEPROM 规则2
在指令的操作数之间的,使用空格进行间隔,采用这种松散方式编写代码的目的是使代码更加清晰。
例如:
CJNE R2, #20H, read1kloop ;END OF EEPROM 规则3
一行最多写一条语句。 规则4
变量定义时,保持对齐。便于阅读和检查内存的使用情况。
例如:
RegLEDLOSS EQU 30H ; VARIABLE ; TESTLED==RegLEDLOSS.0
RegLEDRA EQU 31H ; VARIABLE
RUNLED_Flag EQU 32H ; VARIABLE ; 256ms改变一次RUNLED状态
RUNLED_Def EQU 10H ; STATIC ; 16*32ms=500ms改变一次LED状态
2.注释
注释的原则是有助于对程序的阅读理解,注释不宜太多也不能太少,太少不利于代码理解,太多则会对阅读产生干扰,因此只在必要的地方才加注释,而且注释要准确、易懂、尽可能简洁。注释量一般控制在30%到50%之间。 规则1
程序在必要的地方必须有注释,注释要准确、易懂、简洁。
例如如下注释意义不大:
MOV DXCE1COUNTER, #00H ; 将DXCE1COUNTER赋值为0
而如下的注释则给出了额外有用的信息:
JNZ PcComm_Err ; 假如校验出错 规则2
注释应与其描述的代码相近,对代码的注释应放在其上方或右方(对单条语句的注释)相邻位置,不可放在下面,如放于上方则需与其上面的代码用空行隔开。 规则3
头文件、源文件的头部,应进行注释。注释必须列出:文件名、作者、目的、功能、修改日志等。 规则4
函数头部应进行注释,列出:函数的目的、功能、输入参数、输出参数、涉及到的通用变量和寄存器、调用的其他函数和模块、修改日志等。对一些复杂的函数,在注释中最好提供典型用法。 规则5
对重要代码段的功能、意图进行注释,提供有用的、额外的信息。并在该代码段的结束处加一行注释表示该段代码结束。 规则6
对于所有的常量,变量,数据结构声明(包括数组、结构、类、枚举等),如果其命名不是充分自注释的,在声明时都必须加以注释,说明其含义。 规则 7
维护代码时,要更新相应的注释,删除不再有用的注释。保持代码、注释的一致性,避免产生误解。
3.命名
规则 1
标识符缩写
形成缩写的几种技术:
1) 去掉所有的不在词头的元音字母。如screen写成scrn, primtive写成prmv。
2) 使用每个单词的头一个或几个字母。如Channel Activation写成ChanActiv,Release Indication写成RelInd。
3) 使用变量名中每个有典型意义的单词。如Count of Failure写成FailCnt。
4) 去掉无用的单词后缀 ing, ed等。如Paging Request写成PagReq。
5) 使用标准的或惯用的缩写形式(包括协议文件中出现的缩写形式)。如BSIC(Base Station Identification Code)、MAP(Mobile Application Part)。
关于缩写的准则:
1) 缩写应该保持一致性。如Channel不要有时缩写成Chan,有时缩写成Ch。Length有时缩写成Len,有时缩写成len。
2) 在源代码头部加入注解来说明协议相关的、非通用缩写。
3) 标识符的长度不超过12个字符。 规则2
变量命名约定:<前缀> + 主体 ; 注释
变量命名要考虑简单、直观、不易混淆。
前缀是可选项,表示变量类型,由于汇编中变量多是单字节变量,所以单字节变量可以不加前缀,对于bit和双字节型变量,使用小写的b和d作为前缀表示。
主体是必选项,可多个单词(或缩写)合在一起,每个单词首字母大写,其余部分小写。 规则3
常量的命名
常量的命名规则:单词的字母全部大写,各单词之间用下划线隔开。 规则4
函数的命名
单词首字母为大写,其余均为小写。函数名应以一个动词开头,即函数名应类似一个动词断语或祈使句。
例如:Test_Protect, Check_EEPROM, Init_Para
4.可维护性
规则1
函数和过程中关系较为紧密的代码尽可能相邻。 规则2
每个函数的源程序行数原则上应该少于200行。
对于消息分流处理函数,完成的功能统一,但由于消息的种类多,可能超过200行的限制,不属于违反规定。 规则3
语句嵌套层次不得超过5层。
嵌套层次太多,增加了代码的复杂度及测试的难度,容易出错,增加代码维护的难度。 规则4
避免相同的代码段在多个地方出现。
当某段代码需在不同的地方重复使用时,应根据代码段的规模大小使用函数调用或宏调用的方式代替。这样,对该代码段的修改就可在一处完成,增强代码的可维护性。 规则5
每个函数完成单一的功能,不设计多用途面面俱到的函数。
多功能集于一身的函数,很可能使函数的理解、测试、维护等变得困难。使函数功能明确化,增加程序可读性,亦可方便维护、测试。 规则6
在函数的项目维护文档中,应该指出软件适用的硬件平台及版本。
规则1
程序块使用缩进方式,函数和标号使用空格缩进,程序段混合使用TAB和空格缩进。缩进的目的是使程序结构清晰,便于阅读和理解。
<TAB>默认宽度应为8个空格,由于Word中<TAB>为4个空格,为示范清晰,此处用2个<TAB>代替(下同)。
例如:
MOV R1, #00H
MOV R2, #00H
MOV PMR, #PMRNORMAL
MOV DPS, #FLAGDPTR
MOV DPTR, #ADDREEPROM
read1kloop:
read1kpage:
INC R1
MOVX A, @DPTR
MOV SBUF, A
JNB TI, $
CLR TI
INC DPTR
CJNE R1, #20H, read1kpage
INC R2
MOV R1, #00H
CPL WDI
CJNE R2, #20H, read1kloop ;END OF EEPROM 规则2
在指令的操作数之间的,使用空格进行间隔,采用这种松散方式编写代码的目的是使代码更加清晰。
例如:
CJNE R2, #20H, read1kloop ;END OF EEPROM 规则3
一行最多写一条语句。 规则4
变量定义时,保持对齐。便于阅读和检查内存的使用情况。
例如:
RegLEDLOSS EQU 30H ; VARIABLE ; TESTLED==RegLEDLOSS.0
RegLEDRA EQU 31H ; VARIABLE
RUNLED_Flag EQU 32H ; VARIABLE ; 256ms改变一次RUNLED状态
RUNLED_Def EQU 10H ; STATIC ; 16*32ms=500ms改变一次LED状态
2.注释
注释的原则是有助于对程序的阅读理解,注释不宜太多也不能太少,太少不利于代码理解,太多则会对阅读产生干扰,因此只在必要的地方才加注释,而且注释要准确、易懂、尽可能简洁。注释量一般控制在30%到50%之间。 规则1
程序在必要的地方必须有注释,注释要准确、易懂、简洁。
例如如下注释意义不大:
MOV DXCE1COUNTER, #00H ; 将DXCE1COUNTER赋值为0
而如下的注释则给出了额外有用的信息:
JNZ PcComm_Err ; 假如校验出错 规则2
注释应与其描述的代码相近,对代码的注释应放在其上方或右方(对单条语句的注释)相邻位置,不可放在下面,如放于上方则需与其上面的代码用空行隔开。 规则3
头文件、源文件的头部,应进行注释。注释必须列出:文件名、作者、目的、功能、修改日志等。 规则4
函数头部应进行注释,列出:函数的目的、功能、输入参数、输出参数、涉及到的通用变量和寄存器、调用的其他函数和模块、修改日志等。对一些复杂的函数,在注释中最好提供典型用法。 规则5
对重要代码段的功能、意图进行注释,提供有用的、额外的信息。并在该代码段的结束处加一行注释表示该段代码结束。 规则6
对于所有的常量,变量,数据结构声明(包括数组、结构、类、枚举等),如果其命名不是充分自注释的,在声明时都必须加以注释,说明其含义。 规则 7
维护代码时,要更新相应的注释,删除不再有用的注释。保持代码、注释的一致性,避免产生误解。
3.命名
规则 1
标识符缩写
形成缩写的几种技术:
1) 去掉所有的不在词头的元音字母。如screen写成scrn, primtive写成prmv。
2) 使用每个单词的头一个或几个字母。如Channel Activation写成ChanActiv,Release Indication写成RelInd。
3) 使用变量名中每个有典型意义的单词。如Count of Failure写成FailCnt。
4) 去掉无用的单词后缀 ing, ed等。如Paging Request写成PagReq。
5) 使用标准的或惯用的缩写形式(包括协议文件中出现的缩写形式)。如BSIC(Base Station Identification Code)、MAP(Mobile Application Part)。
关于缩写的准则:
1) 缩写应该保持一致性。如Channel不要有时缩写成Chan,有时缩写成Ch。Length有时缩写成Len,有时缩写成len。
2) 在源代码头部加入注解来说明协议相关的、非通用缩写。
3) 标识符的长度不超过12个字符。 规则2
变量命名约定:<前缀> + 主体 ; 注释
变量命名要考虑简单、直观、不易混淆。
前缀是可选项,表示变量类型,由于汇编中变量多是单字节变量,所以单字节变量可以不加前缀,对于bit和双字节型变量,使用小写的b和d作为前缀表示。
主体是必选项,可多个单词(或缩写)合在一起,每个单词首字母大写,其余部分小写。 规则3
常量的命名
常量的命名规则:单词的字母全部大写,各单词之间用下划线隔开。 规则4
函数的命名
单词首字母为大写,其余均为小写。函数名应以一个动词开头,即函数名应类似一个动词断语或祈使句。
例如:Test_Protect, Check_EEPROM, Init_Para
4.可维护性
规则1
函数和过程中关系较为紧密的代码尽可能相邻。 规则2
每个函数的源程序行数原则上应该少于200行。
对于消息分流处理函数,完成的功能统一,但由于消息的种类多,可能超过200行的限制,不属于违反规定。 规则3
语句嵌套层次不得超过5层。
嵌套层次太多,增加了代码的复杂度及测试的难度,容易出错,增加代码维护的难度。 规则4
避免相同的代码段在多个地方出现。
当某段代码需在不同的地方重复使用时,应根据代码段的规模大小使用函数调用或宏调用的方式代替。这样,对该代码段的修改就可在一处完成,增强代码的可维护性。 规则5
每个函数完成单一的功能,不设计多用途面面俱到的函数。
多功能集于一身的函数,很可能使函数的理解、测试、维护等变得困难。使函数功能明确化,增加程序可读性,亦可方便维护、测试。 规则6
在函数的项目维护文档中,应该指出软件适用的硬件平台及版本。
解决方案 »
免费领取超大流量手机卡,每月29元包185G流量+100分钟通话, 中国电信官方发货