【编程基础第十三讲】代码如何写才最漂亮第二篇

好多小伙伴对编码的格式作用模糊，以为只要完成功能就行，其实这种观点是错误的，一定要重视代码规范，不然你哭的地都找不到。

如何实施:

良好的代码开发习惯对人对己都是非常有用的，良好的代码开发习惯包括，方法封装的独立性，注释添加的合理性，代码布局书写的工整性，当然这些东西没有写的很好也不影响程序的编译与运行，也就是说在初期开发的时候是不受什么影响的，但是对于后期的维护与他人的对你的代码维护就能显示出这方面的重要性了；

今天主要跟大家分享一下一个在程序员这个地方一种公认的书写规范，可以说总结的还是相对全一些的，希望可以对大家有帮助，篇幅可能有点长，如果一篇文章写不完，我会把部分内容放到第二篇中；

一、代码文本注释规范

1）、一般情况下，源程序有效注释量必须在20％以上

注解：需要用SourceCounter工具查看代码的备注说明百分比

2）、源文件头部应进行注释，列出：版权说明、版本号、生成日期、作者、模块功能、主要函数及其功能、修改日志等

注解：例如/*

*Entrance Guard System

*7-Jan-2012Auther.Zhang0.2 Version

*Copyright & the right of find interpretation auther

*synopsis:响应上位机的具体实现,服务于message.c

**/

3）、函数头部应进行注释，列出：函数的目的/功能、输入参数、输出参数、返回值、调用关系（函数、表）等

注解：例如 /*******************************************************************

函数说明 :对函数的简单说明

入口参数 :入口参数及功能

返回类型 :

初始时间 :2012-2-22Lebaishi

修改记录 :2012-3-23支持下载过程中意外断网,下次下载不出错

用途功能:简述此函数的简单用途与目的

********************************************************************/

4）、注释的内容要清楚、明了，含义准确，防止注释二义性

5）、避免在注释中使用缩写，特别是非常用缩写

6）、注释应与其描述的代码相近，对代码的注释应放在其上方或右方（对单条语句的注释）相邻位置，不可放在下面，如放于上方则需与其上面的代码用空行隔开

7）、对于所有有物理含义的变量、常量，如果其命名不是充分自注释的，在声明时都必须加以注释，说明其物理含义。变量、常量、宏的注释应放在其上方相邻位置或右方

8）、数据结构声明(包括数组、结构、类、枚举等)，如果其命名不是充分自注释的，必须加以注释。对数据结构的注释应放在其上方相邻位置，不可放在下面；对结构中的每个域的注释放在此域的右方

9）、全局变量要有较详细的注释，包括对其功能、取值范围、哪些函数或过程存取它以及存取时注意事项等的说明

注解：对于注释，单行的注释要与其上面的内容用空行隔开

10）、避免在一行代码或表达式的中间插入注释

11）、在程序块的结束行右方加注释标记，以表明某程序块的结束

注解：以方便当代码段较长，特别是多重嵌套时的代码可读性

二、代码版本命名规范

1）、代码版本分为：稳定版本和开发版本

版本号的命名参照linux内核命名规则，采用r.x.y点十进制方式命名

r：目前发布的主版本号（与硬件相匹配，与每一版电路板相匹配）

x：偶数代表稳定版本，奇数代表开发中版本

y：开发过程中的错误修补升级版本

为了区分不同版本间的差异，需要在r.x.y后加上-LBS（作者名缩写）

2）、版本号升级及变更说明：

r：跟随硬件电路的升级而变更，例如升级到二系的门禁板，此版本号置为2，依次类推

x：第一次开发置为1，出厂维护无法解决并返回研发室重新开发则置为3（奇数递增），依次类推，每次形成稳定版本出厂时，此版本号置为小于自己的最大偶数

y：开发过程中由0到999递增，出厂后此版本号不变，出厂维护的每次升级将此版本号递增1，出厂维护无法解决并返回研发室重新开发则置为0，重新计数

注解：r是匹配硬件电路的主版本号，x是内部开发的主版本号（奇数），在开发阶段y是调试修改升级的次版本号，在出厂维护阶段y是维护版本号

三、代码函数实现规范

1）、在同一软件产品内，应规划好接口部分标识符（变量、结构、函数及常量）的命名，防止编译、链接时产生冲突

注解：例如在门禁开发中，可以以MJ_开头作为函数首部命名相关函数

2）、用正确的反义词组命名具有互斥意义的变量或相反动作的函数等，提供以下积累（其他待积累）

add / remove begin / end create / destroy put / get

insert / delete first / last get / releaseup / down

add / delete lock / unlock open / closecut / paste

min / max old / new start / stopsend / receive

next / previous source / target show / hidesource / destination

increment / decrement

3）、不要设计多用途面面俱到的函数，一个函数仅完成一件功能

4）、尽量不要编写依赖于其他函数内部实现的函数

注解：例如为了实现某个功能而在模块的函数里面调用其他的函数，这样影响函数的独立性

5）、避免单独使用无意义或含义不清的动词为函数命名（例如：process、handle）

6）、最好不要把与函数返回值类型不同的变量，以系统默认的转换方式或强制转换方式作为返回值返回

注解：如果要返回int 型变量最好让其函数返回类型也为int

7）、设计高扇入、合理扇出的函数（扇出是指一个函数直接调用其它函数的数目，而扇入是指有多少上级函数调用它）

注解：当某个功能简单的函数仅有一个上级函数调用它时，应考虑把它合并到上级函数中，而不必单独存在