为了提高源程序的质量和可维护性，从而最终提高软件产品生产力，特编写此规范。本标准规定了程序设计人员进行程序设计时必须遵循的规范。本规范主要针对单片机编程语言和08编译器而言，包括排版、注释、命名、变量使用、代码可测性、程序效率、质量保证等内容。
1．基本规则
格式清晰、注释简明扼要、命名规范易懂、函数模块化、程序易读易维护、功能准确实现、代码空间效率和时间效率高、适度的可扩展性、单片机编程规范－标识符命名
2．标识符命名 2.1 命名基本原则
（1）命名清晰明了，有明确含义，使用完整单词或约定俗成的缩写。通常，较短的单词可通过去掉元音字母形成缩写；较长的单词可取单词的头几个字母形成缩写。即"见名知意"。（2）命名风格要自始至终保持一致。
（3）命名中若使用特殊约定或缩写，要有注释说明。
（4）同一软件产品内模块之间接口部分的标识符名称之前加上模块标识。
2.2 宏和常量命名
宏和常量用全部大写字母来命名，词与词之间用下划线分隔。对程序中用到的数字均应用有意义的枚举或宏来代替。
2.3 变量命名
变量名用小写字母命名，每个词的第一个字母大写。类型前缀（u8\s8 etc.）全局变量另加前缀g_。
局部变量应简明扼要。局部循环体控制变量优先使用i、j、k等；局部长度变量优先使用len、num等；临时中间变量优先使用temp、tmp等。
2.4 函数命名
函数名用小写字母命名，每个词的第一个字母大写，并将模块标识加在最前面。
2.5 文件命名
一个文件包含一类功能或一个模块的所有函数，文件名称应清楚表明其功能或性质。
每个.c文件应该有一个同名的.h文件作为头文件。
3．注释 3.1 注释基本原则
有助于对程序的阅读理解，说明程序在"做什么"，解释代码的目的、功能和采用的方法。
一般情况源程序有效注释量在30％左右。
注释语言必须准确、易懂、简洁。
边写代码边注释，修改代码同时修改相应的注释，不再有用的注释要删除。
汇编和C中都用"//"，取消";" 不使用段注释" /* */ "（调试时可用）
3.2 文件注释
文件注释必须说明文件名、函数功能、创建人、创建日期、版本信息等相关信息。
修改文件代码时，应在文件注释中记录修改日期、修改人员，并简要说明此次修改的目的。所有修改记录必须保持完整。
文件注释放在文件顶端，用"/*……*/"格式包含。
注释文本每行缩进4个空格；每个注释文本分项名称应对齐。
/***********************************************************
文件名称：
作 者：
版 本：
说 明：
修改记录：
***********************************************************/
3.3 函数注释
3.3.1 函数头部注释
函数头部注释应包括函数名称、函数功能、入口参数、出口参数等内容。如有必要还可增加作者、创建日期、修改记录（备注）等相关项目。
函数头部注释放在每个函数的顶端，用"/*……*/"的格式包含。其中函数名称应简写为Name()，不加入、出口参数等信息。
/***********************************************************
函数名称：
函数功能：
入口参数：
出口参数：
备 注：
***********************************************************/
3.3.2 代码注释
代码注释应与被注释的代码紧邻，放在其上方或右方，不可放在下面。如放于上方则需与其上面的代码用空行隔开。一般少量注释应该添加在被注释语句的行尾，一个函数内的多个注释左对齐；较多注释则应加在上方且注释行与被注释的语句左对齐。
函数代码注释用"//…//"的格式。
通常，分支语句（条件分支、循环语句等）必须编写注释。其程序块结束行"｝"的右方应加表明该程序块结束的标记"end of ……", 尤其在多重嵌套时。
3.4 变量、常量、宏的注释
同一类型的标识符应集中定义，并在定义之前一行对其共性加以统一注释。对单个标识符的注释加在定义语句的行尾。
全局变量一定要有详细的注释，包括其功能、取值范围、哪些函数或过程存取它以及存取时的注意事项等。
注释用"//…//"的格式。
4．函数 4.1 函数设计原则
函数的基本要求：
1）封装性
1) 正确性：程序要实现设计要求的功能。
2) 稳定性和安全性：程序运行稳定、可靠、安全。
3) 可测试性：程序便于测试和评价。
4) 规范／可读性：程序书写风格、命名规则等符合规范。
5) 扩展性：代码为下一次升级扩展留有空间和接口。
6) 全局效率：软件系统的整体效率高。
7) 局部效率：某个模块／子模块/函数的本身效率高。
编制函数的基本原则：
1) 单个函数的规模尽量限制在200行以内（不包括注释和空行）。一个函数只完成一个功能。
2) 函数局部变量的数目一般不超过5～10个。
3) 函数内部局部变量定义区和功能实现区（包含变量初始化）之间空一行。
4) 函数名应准确描述函数的功能。通常使用动宾词组为执行某操作的函数命名。
5) 函数的返回值要清楚明了，尤其是出错返回值的意义要准确无误。
6) 不要把与函数返回值类型不同的变量，以编译系统默认的转换方式或强制的转换方式作为返回值返回。
7) 减少函数本身或函数间的递归调用。
8) 尽量不要将函数的参数作为工作变量。
4.2 函数定义
1) 函数若没有入口参数或者出口参数，应用void明确申明。
2) 函数名称与出口参数类型定义间应该空一格且只空一格。
3) 函数名称与括号()之间无空格。
4) 函数形参必须给出明确的类型定义。
5) 多个形参的函数，后一个形参与前一个形参的逗号分割符之间添加一个空格。
6) 函数体的前后花括号"｛｝" 各独占一行。
4.3 局部变量定义
1) 同一行内不要定义过多变量。
2) 同一类的变量在同一行内定义，或者在相邻行定义。
3) 先定义data型变量，再定义idtata型变量，再定义xdata型变量.（？）
4) 数组、指针等复杂类型的定义放在定义区的最后。
5) 变量定义区不做较复杂的变量赋值。
4.4 功能实现区规范
1) 一行只写一条语句。
2) 注意运算符的优先级，并用括号明确表达式的操作顺序，避免使用默认优先级。
3) 各程序段之间使用一个空行分隔，加以必要的注释。程序段指能完一个较具体的功能的一行或多行代码。程序段内的各行代码之间相互依赖性较强。(1、2、3方式)
4) 不要使用难懂的技巧性很高的语句。
5) 源程序中关系较为紧密的代码应尽可能相邻。
6) 完成简单功能、关系非常密切的一条或几条语句可编写为函数或定义为宏。
|
楼主
标题置顶
标题高亮
