华为c语言编程规范学习笔记（二）

三、函数

背景

函数设计的精髓：编写整洁函数，同时把代码有效组织起来。

整洁函数要求：代码简单直接、不隐藏设计者的意图、用干净利落的抽象和直截了当的控制语句将函数有机组织起来。

代码的有效组织包括逻辑层组织和物理层组织两个方面。

逻辑层，主要是把不同功能的函数通过某种联系组织起来，主要关注模块间的接口，也就是模块的架构。物理层，无论使用什么样的目录或者名字空间等，需要把函数用一种标准的方法组织起来。例如：设计良好的目录结构、函数名字、文件组织等，这样可以方便查找。

原则2.1 一个函数仅完成一件功能。

一个函数实现多个功能给开发、使用、维护都带来很大的困难。 将没有关联或者关联很弱的语句放到同一函数中，会导致函数职责不明确，难以理解，难以测试和改动。

原则2.2 重复代码应该尽可能提炼成函数。

重复代码提炼成函数可以带来维护成本的降低。

重复代码是不良代码最典型的特征之一。在“代码能用就不改”的指导原则之下，大量的烟囱式设计及其实现充斥着各产品代码之中。新需求增加带来的代码拷贝和修改，随着时间的迁移，产品中 堆砌着许多类似或者重复的代码。

项目组应当使用代码重复度检查工具，在持续集成环境中持续检查代码重复度指标变化趋势，并对新增重复代码及时重构。当一段代码重复两次时，即应考虑消除重复，当代码重复超过三次时，应当立刻着手消除重复。一般情况下，可以通过提炼函数的形式消除重复代码。

规则2.1 避免函数过长，新增函数不超过50行（非空非注释行）。

本规则仅对新增函数做要求，对已有函数修改时，建议不增加代码行。

例外：某些实现算法的函数，由于算法的聚合性与功能的全面性，可能会超过50行。

规则2.2 避免函数的代码块嵌套过深，新增函数的代码块嵌套不超过4层。

本规则仅对新增函数做要求，对已有的代码建议不增加嵌套层次。

规则2.3 可重入函数应避免使用共享变量；若需要使用，则应通过互斥手段（关中断、信号量）对其加以保护。

可重入函数是指可能被多个任务并发调用的函数。在多任务操作系统中，函数具有可重入性是多个任务可以共用此函数的必要条件。共享变量指全局变量和static变量。编写C语言的可重入函数时，不应使用static局部变量，否则必须经过特殊处理，才能使函数具有可重入性。

函数若被多个线程调用的话，其结果可能是未知的，当A线程执行时，另外一个使用本函数的线程可能正好被激活，那么当新激活的线程执行到此函数时，将使共享变量被赋予另一个不同的值，所以重新回到A线程后，最终计算的结果很可能不是预想中的结果。

规则2.4  对参数的合法性检查，由调用者负责还是由接口函数负责，应在项目组/模块内应统一规定。 缺省由调用者负责。

对于模块间接口函数的参数的合法性检查这一问题，往往有两个极端现象，即：要么是调用者和被调用者对参数均不作合法性检查，结果就遗漏了合法性检查这一必要的处理过程，造成问题隐患； 要么就是调用者和被调用者均对参数进行合法性检查，这种情况虽不会造成问题，但产生了冗余代码， 降低了效率。

规则2.5 对函数的错误返回码要全面处理。

一个函数（标准库中的函数/第三方库函数/用户定义的函数）能够提供一些指示错误发生的方法。这可以通过使用错误标记、特殊的返回数据或者其他手段，不管什么时候函数提供了这样的机制， 调用程序应该在函数返回时立刻检查错误指示。

规则2.6 设计高扇入，合理扇出（小于7）的函数。

扇出是指一个函数直接调用（控制）其它函数的数目，而扇入是指有多少上级函数调用它。

扇出过大，表明函数过分复杂，需要控制和协调过多的下级函数；而扇出过小，例如：总是1，表明函数的调用层次可能过多，这样不利于程序阅读和函数结构的分析，并且程序运行时会对系统资源如堆栈空间等造成压力。通常函数比较合理的扇出（调度函数除外）通常是3~5。

扇出太大，一般是由于缺乏中间层次，可适当增加中间层次的函数。扇出太小，可把下级函数进一步分解多个函数，或合并到上级函数中。当然分解或合并函数时，不能改变要实现的功能，也不能违背函数间的独立性。

扇入越大，表明使用此函数的上级函数越多，这样的函数使用效率高，但不能违背函数间的独立性而单纯地追求高扇入。公共模块中的函数及底层函数应该有较高的扇入。

较良好的软件结构通常是顶层函数的扇出较高，中层函数的扇出较少，而底层函数则扇入到公共模块中。

规则2.7 废弃代码（没有被调用的函数和变量）要及时清除。

建议2.1 函数不变参数使用const。

不变的值更易于理解/跟踪和分析，把const作为默认选项，在编译时会对其进行检查，使代码更牢固/更安全。

建议2.2 函数应避免使用全局变量、静态局部变量和I/O操作，不可避免的地方应集中使用。

带有内部“存储器”的函数的功能可能是不可预测的，因为它的输出可能取决于内部存储器（如 某标记）的状态。这样的函数既不易于理解又不利于测试和维护。在C语言中，函数的static局部变量 是函数的内部存储器，有可能使函数的功能不可预测，然而，当某函数的返回值为指针类型时，则必须是static的局部变量的地址作为返回值，若为auto类，则返回为错针。

建议2.3 检查函数所有非参数输入的有效性，如数据文件、公共变量等。

函数的输入主要有两种：一种是参数输入；另一种是全局变量、数据文件的输入，即非参数输 入。函数在使用输入参数之前，应进行有效性检查。

建议2.4 函数的参数个数不超过5个。

函数的参数过多，会使得该函数易于受外部（其他部分的代码）变化的影响，从而影响维护工 作。函数的参数过多同时也会增大测试的工作量。 函数的参数个数不要超过5个，如果超过了建议拆分为不同函数。

建议2.5 除打印类函数外，不要使用可变长参函数。

可变长参函数的处理过程比较复杂容易引入错误，而且性能也比较低，使用过多的可变长参函数将导致函数的维护难度大大增加。

建议2.6 在源文件范围内声明和定义的所有函数，除非外部可见，否则应该增加static关键字。

如果一个函数只是在同一文件中的其他地方调用，那么就用static声明。使用static确保只是在声明它的文件中是可见的，并且避免了和其他文件或库中的相同标识符发生混淆的可能性。

建议定义一个STATIC宏，在调试阶段，将STATIC定义为static，版本发布时，改为空，以便于后续的打热补丁等操作。

四、标识符命名与定义

1、通用命名规则

目前比较使用的如下几种命名风格：

unix like风格：单词用小写字母，每个单词直接用下划线 “_” 分割，例如text_mutex，kernel_text_address。

Windows风格：大小写字母混用，单词连在一起，每个单词首字母大写。

匈牙利命名法是计算机程序设计中的一种命名规则，用这种方法命名的变量显示了其数据类型。匈牙利命名主要包括三个部分：基本类型、一个或更多的前缀、一个限定词。但匈牙利命名法存在较多的争议，例如：.NET Framework，微软新的软件开发平台，除了接口类型一般不适用匈牙利命名法。.NET Framework 指导方针建议程序员不要用匈牙利命名法，但是没有指明不要用系统匈牙利命名法还是匈牙利应用命名法，或者是两者都不要用。与此对比，Java的标准库中连接口类型也不加前缀。

标识符的命名规则历来是一个敏感话题，典型的命名风格如unix风格、windows风格等等，从来无法达成共识。我们对标识符定义主要是为了让团队的代码看起来尽可能统一，有利于代码的后续阅读和修改，产品可以根据自己的实际需要指定命名风格。

原则3.1 标识符的命名要清晰、明了，有明确含义，同时使用完整的单词或大家基本可以理解的缩写， 避免使人产生误解。

原则3.2 除了常见的通用缩写以外，不使用单词缩写，不得使用汉语拼音。

较短的单词可通过去掉“元音”形成缩写，较长的单词可取单词的头几个字母形成缩写，一些单词有大家公认的缩写，常用单词的缩写必须统一。协议中的单词的缩写与协议保持一致。对于某个系统使用的专用缩写应该在注视或者某处做统一说明。

一些常见可以缩写的例子：

argument 可缩写为 arg

buffer 可缩写为 buff

clock 可缩写为 clk

command 可缩写为 cmd

compare 可缩写为 cmp

configuration 可缩写为 cfg

device 可缩写为 dev

error 可缩写为 err

hexadecimal 可缩写为 hex

increment 可缩写为 inc

initialize 可缩写为 init

maximum 可缩写为 max

message 可缩写为 msg

minimum 可缩写为 min

parameter 可缩写为 para

previous 可缩写为 prev

register 可缩写为 reg

semaphore 可缩写为 sem

statistic 可缩写为 stat

synchronize 可缩写为 sync

temp 可缩写为 tmp

规则3.1 产品/项目组内部应保持统一的命名风格。

例外：即使产品之前使用匈牙利命名法，新代码也不应当使用。

建议3.1 用正确的反义词组命名具有互斥意义的变量或相反动作的函数等。

建议3.2 尽量避免名字中出现数字编号，除非逻辑上的确需要编号。

示例：如下命名，使人产生疑惑。

#define EXAMPLE_0_TEST_

#define EXAMPLE_1_TEST_

应改为有意义的单词命名

#define EXAMPLE_UNIT_TEST_

#define EXAMPLE_ASSERT_TEST_

建议3.3 标识符前不应添加模块、项目、产品、部门的名称作为前缀。

很多已有代码中已经习惯在文件名中增加模块名，这种写法类似匈牙利命名法，导致文件名不可读，并且带来带来如下问题：

第一眼看到的是模块名，而不是真正的文件功能，阻碍阅读；

文件名太长；

文件名和模块绑定，不利于维护和移植。若foo.c进行重构后，从a模块挪到b模块，若foo.c中有模块名，则需要将文件名从a_module_foo.c改为b_module_foo.c

建议3.4 平台/驱动等适配代码的标识符命名风格保持和平台/驱动一致。

涉及到外购芯片以及配套的驱动，这部分的代码变动（包括为产品做适配的新增代码），应该保持原有的风格。

建议3.5 重构/修改部分代码时，应保持和原有代码的命名风格一致。

2、文件命名规则

建议3.6 文件命名统一采用小写字符。

因为不同系统对文件名大小写处理会不同（如MS的DOS、Windows系统不区分大小写，但是Linux 系统则区分），所以代码文件命名建议统一采用全小写字母命名。

3、变量命名规则

规则3.2 全局变量应增加“g_”前缀。

规则3.3 静态变量应增加“s_”前缀。

规则3.4 禁止使用单字节命名变量，但允许定义i、j、k作为局部循环变量。

建议3.7 不建议使用匈牙利命名法。

变量命名需要说明的是变量的含义，而不是变量的类型。在变量命名前增加类型说明，反而降低了变量的可读性；更麻烦的问题是，如果修改了变量的类型定义，那么所有使用该变量的地方都需 要修改。

建议3.8 使用名词或者形容词＋名词方式命名变量。

4、函数命名规则

建议3.9 函数命名应以函数要执行的动作命名，一般采用动词或者动词＋名词的结构。

建议3.10 函数指针除了前缀，其他按照函数的命名规则命名。

5、宏的命名规则

规则3.5 对于数值或者字符串等等常量的定义，建议采用全大写字母，单词之间加下划线“_”的方式命名（枚举同样建议使用此方式定义）。

规则3.6 除了头文件或编译开关等特殊标识定义，宏定义不能使用下划线“_”开头和结尾。

一般来说，“_”开头、结尾的宏都是一些内部的定义。