程序编写规范

1. 基本要求 1.1 程序结构清析，简单易懂，单个函数的程序行数不得超过100行。 1.2 打算干什么，要简单，直接了当，代码精简，避免垃圾程序。 1.3 尽量使用公共函数，c51的标准库函数谨慎使用。 1.4 不要随意定义全局变量，尽量使用局部变量。 1.5 使用括号以避免二义性。 1.6 非万不得已不要使用浮点运算。一般的小数运算可以使用定点数实现。 2.可读性要求 2.1 可读性第一，效率第二。 2.2 保持注释与代码完全一致。 2.3 每个源程序文件，都有文件头说明，说明规格见规范。 2.4 每个函数，都有函数头说明，说明规格见规范。 2.5 主要变量（结构、联合、类或对象）定义或引用时，注释能反映其含义。 2.7 常量定义（define）有相应说明。 2.8 处理过程的每个阶段都有相关注释说明。 2.9 在典型算法前都有注释。 2.10 利用缩进来显示程序的逻辑结构，缩进量一致并以4个空格为单位。 2.11 循环、分支层次不要超过五层。 2.12 注释可以与语句在同一行，也可以在上行。 2.13 空行和空白字符也是一种特殊注释。 2.14 一目了然的语句不加注释。 2.15 注释的作用范围可以为：定义、引用、条件分支以及一段代码。 3. 结构化要求 3.1 禁止出现两条等价的支路。 3.2 非必要不要使用goto语句。goto一般用于从内循环直接跳到循环外部、检测到 错误直接跳到错误处理程序。影响可读性时禁止使用goto语句。 3.3 用 if 语句来强调只执行两组语句中的一组。 3.4 用 case 实现多路分支。 3.5 避免从循环引出多个出口。 3.6 尽量减少函数的出口。 3.7 避免不必要的分支。 3.8 不要轻易用条件分支去替换逻辑表达式。 4. 正确性与容错性要求 4.1 程序首先是正确，其次是优美。 4.2 无法证明你的程序没有错误，因此在编写完一段程序后，应先回头检查。 4.3 改一个错误时可能产生新的错误，因此在修改前首先考虑对其它程序的影响。 4.4 所有变量在调用前必须被初始化。 4.5 对所有的用户输入，必须进行合法性检查。 4.6 不要比较浮点数的相等，如： 10.0 * 0.1 == 1.0 ， 不可靠。 4.7 函数对接受的参数应该进行合法性检查。 4.8 单元测试也是编程的一部份，提交联调测试的程序必须通过单元测试。 4.9 尽量不要使用==作为判断条件，应该用>=,或<=替代。 5. 可重用性要求 5.1 所有c语言程序文件只包含一个头文件config.h，在config.h中包含其它头文件。 5.2 重复使用的完成相对独立功能的算法或代码应编入一个文件，并且使用头文件 设定一些与硬件相关的参数，这些参数在config.h中定义，模块自己的头文件仅说明 如何设定这些参数。 5.3 公共代码应考虑OO思想，减少外界联系，考虑独立性或封装性。 5.4 尽量少使用与编译器相关的特性。 5.5 取变量占用内存长度用"sizeof(变量类型)"而不用常量。 6.  命名规则 6.1 变量命名 命名必须具有一定的实际意义，要“望文知义”。根据变量的作用域决定名字的长短。 作用域越大，名字越长。在整个程序中都要使用的变量就要长一些；而局部变量就可以 短一些。变量名中每一个单词首字母大以分隔单词。一些习惯单词如OK可以全部大写。 局部变量中可采用如下几个通用变量：TempN，i，j（一般用于循环变量）。 6.2 常量命名和宏定义 常量和宏定义必须具有一定的实际意义; 局部使用的常量和宏定义在#include和函数定义之间; 常量和宏定义必须全部以大写字母来撰写,中间可根据意义的连续性用下划线连接,每一 条定义的右侧必须有一简单的注释,说明其作用; 6.3 函数命名 函数命名一般使用动名或动宾结构，要有实际意义。变量名中每一个单词首字母大写。 6.4 结构体命名 结构体类型命名必须全部用大写字母,原则上前面以下划线开始;结构体变量命名必须用 大小写字母组合，必要时可用下划线间隔。数据定义需注明其用途。 7.  注释 原则上注释要求使用中文; 文件开始注释内容包括:公司名称、版权、作者名称、时间、模块用途、背景介绍等,复 杂的算法需要加上流程说明; 函数注释包括:输入、输出、函数描述、流程处理、全局变量、调用样例等,复杂的函数 需要加上变量用途说明; 程序中注释包括:修改时间和作者、方便理解的注释等; 　　引用一: 文件开头的注释模板 /****************************************Copyright (c)************************************************** **                               广州 周立功 单片机发展有限公司 **                                     研    究    所 **                                        产品一部 ** ** http://www.zlgmcu.com ** **--------------文件信息-------------------------------------------------------------------------------- **文   件   名: **创   建   人: **最后修改日期: **描        述: ** **--------------历史版本信息---------------------------------------------------------------------------- ** 创建人: ** 版  本: ** 日　期: ** 描　述: ** **------------------------------------------------------------------------------------------------------ ** 修改人: ** 版  本: ** 日　期: ** 描　述: ** **--------------当前版本修订------------------------------------------------------------------------------ ** 修改人: ** 日　期: ** 描　述: ** **------------------------------------------------------------------------------------------------------ ********************************************************************************************************/ ******************************************************************/ 　　引用二: 函数开头的注释模板 /********************************************************************************************************* ** 函数名: ** 功能描述: ** 输　入: a--- **　　     b--- **　　     c--- ** 输　出: x 为 1, 表示... **　　　   x 为 0, 表示... ** 全局变量: ** 调用模块: ** 作　者: ** 日　期: **------------------------------------------------------------------------------------------------------- ** 修改人: ** 日　期: **------------------------------------------------------------------------------------------------------ ********************************************************************************************************/ 8.  程序 8.1 程序编码力求简洁，结构清晰，避免太多的分支结构及太过于技巧性的程序， 尽量不采用递归模式。 8.2 编写程序时，亦必须想好测试的方法，换句话说，”单元测试” 的测试方案应 在程序编写时一并拟好。 8.3 注释一定要与程序一致。 8.4 版本封存以后的修改一定要将老语句用/* */ 封闭，不能自行删除或修改,并要 在文件及函数的修改记录中加以记录。在注释中注明封闭代码的修改时间和原因。 8.5 程序中每个block 的开头 ”{" 及"}” 必须对齐，嵌套的block 每进一套， 缩进4个空格。block类型包括if、for、while、do等关键字引出的。 8.6 对于比较大的函数，每个block 和特殊的函数调用，都必须注明其功能 8.7 循环、分支代码，判断条件与执行代码不得在同一行上。 8.8 指针的定义，* 号紧接变量名之前。例：int　*pnsize; 8.9 else if 必须写在一行。 9.  与‘{’、‘}’有关的各项规定： 9.1‘{’、‘}’应独占一行。在该行内可有注释。 9.2‘{’必须另起一行，‘{’ 之后的代码必须缩进4个空格。‘{’与‘}’必须在同 一列上。 9.3 在循环、分支之后若只有一行代码，虽然可省略‘{’、‘}’，但不推荐这么 做。若省略后可能引起歧义，则必须加上‘{’、‘}’。 10. 与空格有关的各项规定。 10.1 在所有两目、三目运算符的两边都必须有空格。在单目运算符两端不必空格。 但在‘—>’、‘::’、‘.’、‘[’、‘]’等运算符前后，及‘&’（取地址）、‘*’（取值）等运算符之后不得有空格。 10.2　for、while、if 等关键词之后应有1个空格，再接‘(’，之后无空格；在结尾 的‘)’前不得有空格。 10.3 调用函数、宏时，‘(’、‘)’前后不得有空格。 10.4 类型强制转换时，‘(’‘)’前后不得有空格 11.  与缩进有关的各项规定 11.1 缩进以4个空格为单位。 11.2 下列情况，代码缩进一个单位:    1. if、else、for、while、do 等之后的代码。    2. 一行之内写不下，折行之后的代码，应在合理的位置进行折行。若有 + - * / 等 运算符，则运算符应在上一行末尾，而不应在下一行的行首。 针对51系列补充 1.  推荐使用编程模式：ram小模式，rom：小模式。 2.  尽量使用无符号数，尽量使用 unsigned char 数。 3.  尽量不使用基本输入输出库函数。 4.  尽量不要使用一般指针。 5.  判断尽量使用>=和<。 6.  尽量避免使用程序延时。 7.  所有循环避免可能出现的死讯循环，例：while(TI==0) TR1=1;(假定串行口使用定时器1）。 8.  中断服务程序尽可能短。 9.  禁止使用递归模式. 10. 一般应用禁止使用浮点运算。 11. 函数参数一般应该少于3个。 针对汇编的补充 1.  尽量使用宏汇编，不要使用小汇编。 2.  使用小汇编时不要使用equ分配变量，要使用data、idata、xdata、bit等分配变量。 3.  混合编程时，尽量先使用c写一个同名函数，然后再生成汇编文件，在这个汇编文件 的基础上编写以避免错误。 参考文献： 《程序设计实践》，大家读一读，在电脑chenmingji的all目录下。 模板在chenmingji的all目录下。 实际代码可以参考Small RTOS 51 v1.12.1的代码，在电脑chenmingji的small rtos目录下。 增加一：注意程序版本号的标注。每一次程序的升级应注明升级日期、版本号、修改内容等，便于日后的         查询。同时注意保存原有的版本一段时间（一般为一年以内）。