个人代码书写规范

                                个人代码书写规范

————2012-3-20，版本0.0.0-LBS

一、代码版本命名规范

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

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

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

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

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

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

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

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

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

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

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

二、代码变量命名规范
       2-1、通用的变量：循环loop，计数count，累加sum         （其他待积累）

    2-2、与功能相关：用于记录数据_reg  (register：记录)

                 标志位_flag

注解：如果需要用到这样功能的，描述放到变量名之后，例如***_flag

    2-3、与范围相关：全局变量    g

                 局部变量    local  ——  l

                 静态变量    static  ——  s

                 被外部引用  extern  ——  e

注解：静态变量只能出现在局部变量里，被外部引用只能出现在全局变量里，所以对于一个变量而言，此处与范围相关的描述只能有一种可能。

    2-4、数据类型：bool     —— b

                byte       —— by

                float       —— f

                double     —— d

                char       —— c  

                int         —— i (如果变量类型有unsigned的，在描述符后加上u，例iu)   

               结构体变量 —— s  （例如struct Long_Time ls_timer，局部结构体变量）

注解：此处结构体变量与静态变量都用s描述，只是描述等级不一样(描述等级为一个变量首先要反映出来的信息描述为最高！)，而且不能用静态方式定义结构体变量的，结构体变量只有全局或局部之分

    2-5、指针的描述放到所有描述之前（如果用到指针的话）

               指针      —— p

               二重指针  ——  pp（以此类推）

注解：例如int *pli_timer=&gi_sum;

变量命名公式：变量名=范围描述+数据类型+变量名英文释义

2-6、命名中若使用特殊约定或缩写，则要有注释说明

注解：应该在源文件的开始之处，对文件中所使用的缩写或约定，进行必要的注释说明

2-7、自己特有的命名风格，要自始至终保持一致，不可来回变化

三、代码函数实现规范      

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

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

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

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

insert / delete        first / last          get / release up / down

add / delete          lock / unlock       open / close cut / paste  

min / max           old / new          start / stop send / receive

next / previous      source / target      show / hide source / destination

increment / decrement

        

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

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

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

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

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

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

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

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

四、代码格式书写规范

4-1、程序块要采用缩进风格编写（缩进空格以source singht的一个“Tab”键为基准，四个字节）

4-2、定义所有局部变量后需要加个回车空行

4-3、一行只写一条语句，即不允许把多个短语句写在一行中

4-4、if、for、do、while、case、switch、default等语句自占一行，且无论执行语句的多少都要加括号{ }，且程序块的分界符‘{’和‘}’应各独占一行并且位于同一列，同时与引用它们的语句左对齐。

注解：形如if(*********)

 ｛

      return 0;

  ｝

4-5、if、for、while、switch等与后面的括号间应加空格，使if等关键字更为突出明显

4-6、if语句尽量加上else分支，对没有else分支的语句要小心对待；switch语句必须有default分支

4-7、逗号、分号只在后面加一个空格

注解：例如for（loop=0； loop<100； loop++）或int  loop=0， num_reg=0；

4-8、比较操作符, 赋值操作符"="、 "+="，算术操作符"+"、"%"，逻辑操作符"&&"、"&"，位域操作符"<<"、"^"等双目操作符的前后加空格

注解：例如 if (current_time  >=  MAX_TIME_VALUE) 

a = b + c;

a *= 2;

a = b ^ 2;

4-9、"!"、"~"、"++"、"--"、"&"（地址运算符）等单目操作符前后不加空格(例如i++)

4-10、"->"、"."前后不加空格

五、代码框架搭建规范  

5-1、尽量将高扇入的底层函数分类的归属到各自的源文件里，方便不同的应用工程移植

5-2、尽量将产品功能变化牵涉较多的函数归类到一个源文件，例如门禁开发中的逻辑关系的具体实现源文件

六、代码文本注释规范

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

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

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

注解：例如 /*

    * Entrance Guard System

    * 7-Jan-2012 Auther.Zhang 0.2 Version

  * Copyright & the right of find interpretation auther

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

    *

     */

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

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

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

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

   返回类型  :

   初始时间  :2012-2-22 Lebaishi

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

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

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

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

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

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

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

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

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

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

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

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

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

七、代码优化方法积累

7-1、尽量用乘法或其它方法代替除法，特别是浮点运算中的除法

注解：浮点运算除法要占用较多CPU资源

八、代码质量检测标准

8-1、代码质量保证优先原则

      （1）正确性，指程序要实现设计要求的功能。

      （2）稳定性、安全性，指程序稳定、可靠、安全。

      （3）可测试性，指程序要具有良好的可测试性。

      （4）规范/可读性，指程序书写风格、命名规则等要符合规范。

      （5）全局效率，指软件系统的整体效率。

      （6）局部效率，指某个模块/子模块/函数的本身效率。

      （7）个人表达方式/个人方便性，指个人编程习惯。

8-2、通过SourceCounter工具检测的代码注释量达到代码的20%，公共变量必须有较明细的功能记录

8-3、多线程的中的子线程退出必需采用主动退出方式，即通过return出口

8-4、过程/函数中分配的内存，在过程/函数退出之前要释放，不得引用已经释放的内存空间

8-5、过程/函数中申请的（为打开文件而使用的）文件句柄，在过程/函数退出之前要关闭

8-6、用PC-Lint工具检测，不得有内存超出操作越界等错误