背景：

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

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

    疑问:
    不隐藏设计者的意图 这句话咋理解？

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

原则：

1. 一个函数仅完成一件功能

一个函数实现多个功能给开发、使用、维护都带来很大的困难。

将没有关联或者关联很弱的语句放到同一函数中，会导致函数职责不明确，难以理解，难以测试和改动。

案例： realloc
在标准C语言中， realloc是一个典型的不良设计。这个函数基本功能是重新分配内存，但它承担了太多的其他任务：如果传入的指针参数为NULL就分配内存，如果传入的大小参数为0就释放内存，如果可行则就地重新分配，如果不行则移到其他地方分配。如果没有足够可用的内存用来完成重新分配（扩大原来的内存块或者分配新的内存块），则返回NULL，而原来的内存块保持不变。这个函数不易扩展，容易导致问题。例如下面代码容易导致内存泄漏：

char *buffer = (char *)malloc(XXX_SIZE);
.....
buffer = (char *)realloc(buffer, NEW_SIZE);

如果没有足够可用的内存用来完成重新分配，函数返回为NULL，导致buffer原来指向的内存被丢失。

延伸阅读材料：《 敏捷软件开发：原则、模式与实践》 第八章，单一职责原则(SRP)

2. 重复代码应该尽可能提炼成函数

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

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

项目组应当使用代码重复度检查工具，在持续集成环境中持续检查代码重复度指标变化趋势，并对新增重复代码及时重构。当一段代码重复两次时，即应考虑消除重复，当代码重复超过三次时，应当立刻着手消除重复。

3. 避免函数过长，新增函数不超过 50 行 （非空非注释行）

过长的函数往往意味着函数功能不单一，过于复杂。

函数的有效代码行数，即NBNC（非空非注释行）应当在[1，50]区间。

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

延伸阅读材料： 业界普遍认为一个函数的代码行不要超过一个屏幕，避免来回翻页影响阅读；一般的代码度量工具建议都对此进行检查，例如Logiscope的函数度量：”Number of Statement” （函数中的可执行语句数）建议不超过20行，QA C建议一个函数中的所有行数（包括注释和空白行）不超过50行。

4. 避免函数的代码块嵌套过深，新增函数的代码块嵌套不超过4层

函数的代码块嵌套深度指的是函数中的代码控制块（例如：if、for、while、switch等）之间互相包含的深度。每级嵌套都会增加阅读代码时的脑力消耗，因为需要在脑子里维护一个“栈”（比如，进入条件语句、进入循环„„）。应该做进一步的功能分解，从而避免使代码的阅读者一次记住太多的上下文。

优秀代码嵌套深度参考值：[1, 4]。

错误示例：代码嵌套深度为5层：

void serial (void)
{
    if (!Received)
    {
        TmoCount = 0;
         switch (Buff)
        {
            case AISGFLG:
                if ((TiBuff.Count > 3)&& ((TiBuff.Buff[0] == 0xff) || (TiBuf.Buff[0] == CurPa.ADDR)))
                {
                    Flg7E = false;
                    Received = true;
                }
                else
                {
                    TiBuff.Count = 0;
                    Flg7D = false;
                    Flg7E = true;
                }
                break;
            default:
                break;
        }
    }
}

疑问：我怎么看着上面的代码嵌套深度为3 ?

5. 可重入函数应避免使用共享变量；

若需要使用，则应通过互斥手段（关中断、信号量）对其加以保护

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

示例：函数square_exam返回g_exam平方值。那么如下函数不具有可重入性。

int g_exam;
unsigned int example( int para )
{
    unsigned int temp;
    g_exam = para; // （**）
    temp = square_exam ( );
    return temp;
}

此函数example()若被多个线程调用的话，其结果可能是未知的，因为当（**）语句刚执行完后，另外一个使用本函数的线程可能正好被激活，那么当新激活的线程执行到此函数时，将使g_exam赋于另一个不同的para值，所以当控制重新回到“temp =square_exam ( )”后，计算出的temp很可能不是预想中的结果。

此函数example()应如下改进：

int g_exam;
unsigned int example( int para )
{
    unsigned int temp;
    [申请信号量操作] // 若申请不到“信号量”，说明另外的进程正处于
    g_exam = para; //给g_exam赋值并计算其平方过程中（即正在使用此
    temp = square_exam( ); // 信号），本进程必须等待其释放信号后，才可继
    [释放信号量操作] // 续执行。其它线程必须等待本线程释放信号量后
    // 才能再使用本信号。
    return temp;
}

6. 对参数的合法性检查，

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

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

7. 对函数的错误返回码要全面处理

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

8. 设计高扇入，合理扇出（小于7）的函数

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

02_函数 - 图1

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

扇出太大，一般是由于缺乏中间层次，可适当增加中间层次的函数。扇出太小，可把下级函数进一步分解多个函数，或合并到上级函数中。当然分解或合并函数时，不能改变要实现的功能，也不能违背函数间的独立性。扇入越大，表明使用此函数的上级函数越多，这样的函数使用效率高，但不能违背函数间的独立性而单纯地追求高扇入。公共模块中的函数及底层函数应该有较高的扇入。

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

9. 废弃代码（没有被调用的函数和变量) ) 要及时清除

程序中的废弃代码不仅占用额外的空间，而且还常常影响程序的功能与性能，很可能给程序的测试、维护等造成不必要的麻烦。

[建议]

1、函数不变参数使用const

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

正确示例：C99标准 7.21.4.4 中strncmp 的例子，不变参数声明为const。

int strncmp(const char *s1, const char *s2, register size_t n)
{
    register unsigned char u1, u2;
    while (n-- > 0)
    {
        u1 = (unsigned char) *s1++;
        u2 = (unsigned char) *s2++;
        if (u1 != u2)
        {
            return u1 - u2;
        }
        if (u1 == '\0')
        {
            return 0;
        }
    }
    return 0;
}

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

带有内部“存储器”的函数的功能可能是不可预测的，因为它的输出可能取决于内部存储器（如某标记）的状态。这样的函数既不易于理解又不利于测试和维护。在C语言中，函数的static局部变量是函数的内部存储器，有可能使函数的功能不可预测。

错误示例：如下函数，其返回值（即功能）是不可预测的。

unsigned int integer_sum( unsigned int base )
{
    unsigned int index;
    static unsigned int sum = 0;// 注意，是static类型的。
    // 若改为auto类型，则函数即变为可预测。
    for (index = 1; index <= base; index++)
    {
        sum += index;
    }
    return sum;
}

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

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

4、函数的参数个数不超过5个

函数的参数过多，会使得该函数易于受外部（其他部分的代码）变化的影响，从而影响维护工作。函数的参数过多同时也会增大测试的工作量。

函数的参数个数不要超过5个，如果超过了建议拆分为不同函数。

5、除打印类函数外，不要使用可变长参函数。

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

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

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

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

#ifdef _DEBUG
#define STATIC static
#else
#define STATIC
#endif