C语言编程规范

C语言编程规范

6 函数与过程
6.1 函数的功能与规模设计
函数应当短而精美，而且只做一件事。不要设计多用途面面俱到的函数，多功能集于一身的函数，很可能使函数的理解、测试、维护等变得困难。
6.2 函数的返回值
(1)对于函数的返回位置，尽量保持单一性，即一个函数尽量做到只有一个返回位置。(单入口单出口)。
要求大家统一函数的返回值，所有的函数的返回值都将以编码的方式返回。
例如编码定义如下：
#define CM_POINT_IS_NULL CMMAKEHR(0X200)
:
:
参考函数实现如下：
LONG 函数名(参数,……)
{
LONG lResult; //保持错误号
lResult=CM_OK;
//如果参数有错误则返回错误号
if(参数==NULL)
{
lResult=CM_POINT_IS_NULL;
goto END;
}
……
END:
return lResult;
}
调用者对所调用函数的错误返回码要仔细、全面地处理
6.3 变量的使用
当你确实需要时才用全局变量，函数间应尽可能使用参数、返回值传递消息。
6.4 函数参数
在同一项目组应明确规定对接口函数参数的合法性检查
(1)防止将函数的参数作为工作变量。将函数的参数作为工作变量，有可能错误地改变参数内容，所以很危险。对必须改变的参数，最好先用局部变量代之，最后再将该局部变量的内容赋给该参数。
(2)避免设计多参数函数，不使用的参数从接口中去掉，目的减少函数间接口的复杂度。

7 可测性
7.1 准备测试代码、测试用例
(1)编程的同时要为单元测试选择恰当的测试点，并仔细构造测试代码、测试用例，同时给出明确的注释说明。测试代码部分应作为(模块中的)一个子模块，以方便测试代码在模块中的安装与拆卸(通过调测开关)
(2)在进行集成测试/ 系统联调之前，要构造好测试环境、测试项目及测试用例，同时仔细分析并优化测试用例，以提高测试效率。好的测试用例应尽可能模拟出程序所遇到的边界值、各种复杂环境及一些极端情况等。
(3)在编写代码之前，应预先设计好程序调试与测试的方法和手段，并设计好各种调测开关及相应测试代码如打印函数等。程序的调试与测试是软件生存周期中很重要的一个阶段，如何对软件进行较全面、高率的测试并尽可能地找出软件中的错误就成为很关键的问题。因此在编写源代码之前，除了要有一套比较完善的测试计划外，还应设计出一系列代码测试手段，为单元测试、集成测试及系统联调提供方便。
7.2 使用断言来发现软件问题，提高代码可测性
(1)断言是对某种假设条件进行检查(可理解为若条件成立则无动作，否则应报告)，它可以快速发现并定位软件问题，同时对系统错误进行自动报警。断言可以对在系统中隐藏很深，用其它手段极难发现的问题进行定位，从而缩短软件问题定位时间，提高系统的可测性。实际应用时，可根据具体情况灵活地设计断言。
示例：下面是C语言中的一个断言，用宏来设计的。(其中NULL为0L)
#ifdef _EXAM_ASSERT_TEST_  // 若使用断言测试
void exam_assert( char * file_name, unsigned int line_no )
{
printf( "\n[EXAM]Assert failed: %s, line %u\n",
file_name, line_no );
abort( );
}
#define  EXAM_ASSERT( condition )
if (condition) // 若条件成立，则无动作
NULL;
else  // 否则报告
exam_assert( __FILE__, __LINE__ )
#else  // 若不使用断言测试
#define EXAM_ASSERT(condition)  NULL
#endif  /* end of ASSERT */
(2)用断言来检查程序正常运行时不应发生但在调测时有可能发生的非法情况。
(3)不能用断言来检查最终产品肯定会出现且必须处理的错误情况。断言是用来处理不应该发生的错误情况的，对于可能会发生的且必须处理的情况要写防错程序，而不是断言。如某模块收到其它模块或链路上的消息后，要对消息的合理性进行检查，此过程为正常的错误检查，不能用断言来实现。
(4)对较复杂的断言加上明确的注释，澄清断言含义并减少不必要的误用。
(5)用断言确认函数的参数。示例：假设某函数参数中有一个指针，那么使用指针前可对它检查，如下。
int exam_fun( unsigned char *str )
{
EXAM_ASSERT( str != NULL );  // 用断言检查“假设指针不为空”这个条件
... //other program code
}
7.3 版本控制
(1)正式软件产品中应把断言及其它调测代码去掉(即把有关的调测开关关掉)，加快软件运行速度。
(2)在软件系统中设置与取消有关测试手段，不能对软件实现的功能等产生影响——即有测试代码的软件和关掉测试代码的软件，在功能行为上应一致。
(3)用调测开关来切换软件的DEBUG 版和正式版，而不要同时存在正式版本和DEBUG 版本的不同源文件，以减少维护的难度
(4)软件的DEBUG 版本和发行版本应该统一维护，不允许分家，并且要时刻注意保证两个版本在实现功能上的一致性。

10 代码编辑、编译、审查
(1)打开编译器的所有告警开关对程序进行编译。
(2)在产品软件(项目组)中，要统一编译开关选项。
(3)通过代码走读及审查方式对代码进行检查。代码走读主要是对程序的编程风格如注释、命名等以及编程时易出错的内容进行检查，可由开发人员自己或开发人员交叉的方式进行；代码审查主要是对程序实现的功能及程序的稳定性、安全性、可靠性等进行检查及评审，可通过自审、交叉审核或指定部门抽查等方式进行。
(4)测试部测试产品之前，应对代码进行抽查及评审。
(5)编写代码时要注意随时保存，并定期备份，防止由于断电、硬盘损坏等原因造成代码丢失。
(6)同产品软件(项目组)内，最好使用相同的编辑器，并使用相同的设置选项。同一项目组最好采用相同的智能语言编辑器，如Elipse等，并设计、使用一套缩进宏及注释宏等，将缩进等问题交由编辑器处理。
(7)要小心地使用编辑器提供的块拷贝功能编程。当某段代码与另一段代码的处理功能相似时，许多开发人员都用编辑器提供的块拷贝功能来完成这段代码的编写。由于程序功能相近，故所使用的变量、采用的表达式等在功能及命名上可能都很相近，所以使用块拷贝时要注意，除了修改相应的程序外，一定要把使用的每个变量仔细查看一遍，以改成正确的。不应指望编译器能查出所有这种错误，比如当使用的是全局变量时，就有可能使某种错误隐藏下来。
(8)合理地设计软件系统目录，方便开发人员使用。方便、合理的软件系统目录，可提高工作效率。目录构造的原则是方便有关源程序的存储、查询、编译、链接等工作，同时目录中还应具有工作目录----所有的编译、链接等工作应在此目录中进行，工具目录----有关文件编辑器、文件查找等工具可存放在此目录中。
(9)某些语句经编译后产生告警，但如果你认为它是正确的，那么应通过某种手段去掉告警信息。例如，在Borland C/C++中，可用“#pragma  warn”来关掉或打开某些告警。
示例：
#pragma warn -rvl // 关闭告警
int examples_fun( void )
{
// 程序，但无return语句。
}
#pragma warn +rvl // 打开告警
编译函数examples_fun时本应产生“函数应有返回值”告警，但由于关掉了此告警信息显示，所以编译时将不会产生此告警提示。
使用代码检查工具(如C 语言用PC-Lint )对源程序检查，使用软件工具(如 LogiSCOPE )进行代码审查。

11 代码测试、维护
(1)单元测试要求至少达到语句覆盖。
(2)单元测试开始要跟踪每一条语句，并观察数据流及变量的变化。
(3)清理、整理或优化后的代码要经过审查及测试。
(4)代码版本升级要经过严格测试。
(5)使用工具软件对代码版本进行维护。
(6)正式版本上软件的任何修改都应有详细的文档记录。
(7)发现错误立即修改，并且要记录下来。
(8)关键的代码在汇编级跟踪。
(9)仔细设计并分析测试用例，使测试用例覆盖尽可能多的情况，以提高测试用例的效率。
(10)尽可能模拟出程序的各种出错情况，对出错处理代码进行充分的测试。
(11)仔细测试代码处理数据、变量的边界情况。
(12)保留测试信息，以便分析、总结经验及进行更充分的测试。
(13)不应通过“ 试” 来解决问题，应寻找问题的根本原因。
(14)对自动消失的错误进行分析，搞清楚错误是如何消失的。
(15)修改错误不仅要治表，更要治本。
(16)测试时应设法使很少发生的事件经常发生。
(17)明确模块或函数处理哪些事件，并使它们经常发生。
(18)坚持在编码阶段就对代码进行彻底的单元测试，不要等以后的测试工作来发现问题。
(19)去除代码运行的随机性(如去掉无用的数据、代码及尽可能防止并注意函数中的“内部寄存器”等)，让函数运行的结果可预测，并使出现的错误可再现。

12 宏
(1)用宏定义表达式时，要使用完备的括号。示例：如下定义的宏都存在一定的风险。
#define RECTANGLE_AREA( a, b ) a * b
#define RECTANGLE_AREA( a, b ) (a * b)
#define RECTANGLE_AREA( a, b ) (a) * (b)
正确的定义应为：
#define RECTANGLE_AREA( a, b ) ((a) * (b))
(2)将宏所定义的多条表达式放在大括号中。示例：下面的语句只有宏的第一条表达式被执行。为了说明问题，for语句的书写稍不符规范。
#define INTI_RECT_VALUE( a, b )\
a = 0;\
b = 0;
for (index = 0; index < RECT_TOTAL_NUM; index++)
INTI_RECT_VALUE( rect.a, rect.b );
正确的用法应为：
#define INTI_RECT_VALUE( a, b )\
{\
a = 0;\
b = 0;\
}
for (index = 0; index < RECT_TOTAL_NUM; index++)
{
INTI_RECT_VALUE( rect[index].a, rect[index].b );
}