软件接口API规范

软件接口API规范
                            
 
   
 
                          
                          
 
 
                            
 
                            
 
   
 
 
 当前版本：V1.0
版本日期:2018-01-30


 
 
 
第一章 内存管理
避免动态分配内存，以静态方式分配  
      说明：为提高内存管理的稳定性和可靠性，算法模块可提出内存申请请求，由外部接口进行统一分配内存，禁止在算法模块内部进行动态内存的申请和释放。  


内存分配要求4字节对齐
      说明：内存对齐可提高数据的访问速度和效率。模块内部若是开辟大块内存，可注明要求 8 字节对齐、128 字节对齐等信息。具体到数据类型转换或数据赋值时，如 char *p; *(int*)p = 4;    此时的 p 要 32 位对齐  
除数据表外，模块内部不允许存在全局变量  
      说明：为防止在集成中存在局部变量与全局变量同名等现象，要求模块禁止使用全局变量。建议所有变量均应归纳至句柄、参数结构体、输入出结构体三类结构体中。   【注】：模块可允许存在一些数据表作为全局变量，但数据表的命名要要与别的数据表、变量要严格区分，另外，对于大型的表须以段的形式声明，小的表以static形式定义，在模块进行提交时需进行详细的说明。


























第二章 函数管理
在函数入口处或者数据对齐处，添加断言语句
   说明：在PC 或嵌入式系统均支持断言语句，断言语句 assert 可以看成一个在任何系统 状态下都可以安全使用的无害测试手段，在函数入口处，利用断言可以有效检测输入参数的有效性，特别对于数据内存对齐的地方，添加断言语句能够对关心的位置进行有效的检测，避免很多隐藏的BUG 的产生。  


函数内部/参量不许存在大型数组和结构体变量  
   说明：由于函数内部调用结构体类型变量，需将这个结构体内存空间加载到当前函数堆栈，易引起堆栈溢出等不稳定现象发生，建议在函数里内部使用临时变量或临时结构体变量不要过多。模块函数内部和参量中不允许存在大型数组/结构体类型变量，必须以数组指针/结构体指针形式存在。   
内部函数/变量不被外部文件调用需用 static 定义  
   说明：对于文件内部的函数/变量是指当前函数/变量仅被当前文件的函数所调用，外部 函数不得调用该函数/变量，采用static关键字定义能够让编译器清楚当前函数/变量的引用范围，在外部也不需要对函数/变量进行外部声明。但注意，使用static把它局限在内部文件使用，请详细检查参数的有效性。因为static函数参数/变量，一般不需要参数检查，请调用者自行在调用处保证参数可靠。  


建议设计高扇入、合理扇出（小于5 ）的函数  
   说明：扇出是指一个函数直接调用 （控制）其它函数的数目，而扇入是指有多少上级函 数调用它。扇出过大，表明函数过分复杂，需要控制和协调过多的下级函数；而扇出过小，如总是1，表明函数的调用层次可能过多，这样不利程序阅读和函数结构的分析，并且程序运行时会对系统资源如堆栈空间等造成压力。函数较合理的扇出（调度函数除外）通常是3-5。扇出太大，一般是由于缺乏中间层次，可适当增加中间层次的函数。扇出太小，可把下级函数进一步分解多个函数，或合并到上级函数中。当然分解或合并函数时，不能改变要实现的功能，也不能违背函数间的独立性。扇入越大，表明使用此函数的上级函数越多，这样的函数使用效率高，但不能违背函数间的独立性而单纯地追求高扇入。公共模块中的函数及底层函数应该有较高的扇入。较良好的软件结构通常是顶层函数的扇出较高，中层函数的扇出较少，而底层函数则扇入到公共模块中。   
对函数的错误返回码要仔细、全面地处理  
  说明：  
       1. 定义所有函数的错误码信息，函数返回值必须是错误码中的一个  
       2. 函数的每种出错返回值的意义要清晰、明了、准确，防止使用者误用、理解错误  
        或忽视错误返回码。  
       3. 在开发中函数异常返回值必须有相应的处理和告警信息。 
尽可能确保接口的简单和明了  
   说明：模块集成时不关注各个子模块，子模块的相互调用由模块内部进行操作，因此建议各子模块接口并入模块接口相应位置进行处理，当需融合多个子模块时，将子模块对应结构纳入到外部句柄、参数结构体、输入/ 出结构体中。特别的，一个模块只提供一组标准接口。  
建议函数功能较为单一，防止循环体过于复杂  
   说明：多功能集于一身的函数，很可能使函数的理解、测试、维护等变得困难。不要设计多用途面面俱到的函数。建议一个函数只做一件事情，不要设计多用途的函数，要控制函数体的整体规模，特别注意循环体不要过于复杂   
检查函数所有输入参数的有效性
    说明：函数的输入主要有两种：一种是参数输入；另一种是全局变量、数据文件的输入， 即非参数输入。函数在使用输入之前，应进行必要的检查。  
编写可重入函数，尽量避免函数带有 “记忆”功能  
    说明：要保证函数的功能是可以预测且可重入的，这就要求函数只要输入数据相同就应 产生同样的输出。有“记忆”功能的函数，其行为可能是不可预测的，因为它的行为可能取决于某种 ‘“记忆状态”。这样的函数既不易于理解又不利于测试和维护。编写C/C++语言的可重入函数时，不应使用 static 局部变量，否则必须经过特殊处理，才能使函数具有可重入性。在 C/C++语言中，函数的 static 局部变量是函数的内部存储器，有可能使函数的功能不可预测，然而，当某函数的返回值为指针类型时，则必须是STATIC 的局部变量的地址作为返回值，若为 AUTO 类，则返回为野指针。建议尽量少用 static 局部变量，除非必须。  
    示例：如下函数，其返回值 （即功能）是不可预测的。  
    unsigned int integer_sum( unsigned int base )  
    {  
        unsigned int index;  
        static unsigned int sum = 0; //  注意，是 static 类型的。  
                               //  若改为 auto 类型，则函数即变为可预测。  
        f or (index = 1; index <= base; index++)  
        {  
            sum += index;  
        }  
        return sum;  
    }  


防止将函数的参数作为工作变量  
    说明：将函数的参数作为工作变量，有可能错误地改变参数内容，所以很危险。对必须 改变的参数，最好先用局部变量代之，最后再将该局部变量的内容赋给该参数。  
    示例：下函数的实现不太好。  
    void sum_data( unsigned int num, int *data, int *sum )  
    {  
        unsigned int count;  
        *sum = 0;  
        for (count = 0; count < num; count++)  
        {  
            *sum  += data[count]; // sum 成了工作变量，不太好。  
        }  
     }  
    若改为如下，则更好些。  
    void sum_data( unsigned int num, int *data, int *sum )  
     {  
        unsigned int count ;  
        int sum_temp;  
        sum_temp = 0;  
        for (count = 0; count < num; count ++)  
        {  
            sum_temp  += data[count];   
        }  
        *sum = sum_temp;  
     }  
无任何数据处理的小函数建议合并到上一级
    说明：模块中函数划分的过多，一般会使函数间的接口变得复杂。所以过小的函数，特 别是扇入很低的或功能不明确的函数，不值得单独存在。  


不要使用函数本身或函数间的递归调用
    说明：递归调用特别是函数间的递归调用 （如A->B->C->A ），影响程序的可理解性ÿ