三万字长文总结C语言规范

最新推荐文章于 2024-03-31 22:11:39 发布

原创

最新推荐文章于 2024-03-31 22:11:39 发布

· 387 阅读

5 ·

版权

文章标签：

#c语言 #数据库 #开发语言

1.头文件

若包含了头文件aa.h，则就引入了新的依赖：一旦aa.h被修改，任何直接和间接包含aa.h代码都会被重新编译。如果aa.h又包含了其他头文件如bb.h，那么bb.h的任何改变都将导致所有包含了aa.h的代码被重新编译，在敏捷开发方式下，代码会被频繁构建，漫长的编译时间将极大的阻碍频繁构建。因此，我们倾向于减少包含头文件，尤其是在头文件中包含头文件，以控制改动代码后的编译时间。

合理的头文件划分体现了系统设计的思想，但是从编程规范的角度看，仍然有一些通用的方法，用来合理规划头文件。

原则1.1 头文件中适合放置接口的声明，不适合放置实现。

说明：头文件是模块（Module）或单元（Unit）的对外接口。头文件中应放置对外部的声明，如对外提供的函数声明、宏定义、类型定义等。

内部使用的函数（相当于类的私有方法）声明不应放在头文件中。

内部使用的宏、枚举、结构定义不应放入头文件中。

变量定义不应放在头文件中，应放在.c文件中。
原则1.2 头文件应当职责单一。

说明：头文件过于复杂，依赖过于复杂是导致编译时间过长的主要原因。很多现有代码中头文件过大，职责过多，再加上循环依赖的问题，可能导致为了在.c中使用一个宏，而包含十几个头文件。
原则1.3 头文件应向稳定的方向包含。

产品依赖于平台，平台依赖于标准库。某产品线平台的代码中已经包含了产品的头文件，导致平台无法单独编译、发布和测试，是一个非常糟糕的反例。

除了不稳定的模块依赖于稳定的模块外，更好的方式是两个模块共同依赖于接口，
规则1.1 每一个.c文件应有一个同名.h文件，用于声明需要对外公开的接口。

说明：如果一个.c文件不需要对外公布任何接口，则其就不应当存在，除非它是程序的入口，如main函数所在的文件。
规则1.2 禁止头文件循环依赖。

说明：头文件循环依赖，指a.h包含b.h，b.h包含c.h，c.h包含a.h之类导致任何一个头文件修改，都导致所有包含了a.h/b.h/c.h的代码全部重新编译一遍。
规则1.3 .c/.h文件禁止包含用不到的头文件。

说明：很多系统中头文件包含关系复杂，开发人员为了省事起见，可能不会去一一钻研，直接包含一切想到的头文件。
规则1.4 头文件应当自包含。

说明：简单的说，自包含就是任意一个头文件均可独立编译。如果一个文件包含某个头文件，还要包含另外一个头文件才能工作的话，就会增加交流障碍，给这个头文件的用户增添不必要的负担。
规则1.5 总是编写内部#include保护符（#define 保护）。

说明：多次包含一个头文件可以通过认真的设计来避免。如果不能做到这一点，就需要采取阻止头文件内容被包含多于一次的机制。

所有头文件都应当使用#define 防止头文件被多重包含，命名格式为FILENAME_H，为了保证唯一性，更好的命名是PROJECTNAME_PATH_FILENAME_H。
规则1.6 禁止在头文件中定义变量。

说明：在头文件中定义变量，将会由于头文件被其他.c文件包含而导致变量重复定义。
规则1.7 只能通过包含头文件的方式使用其他.c提供的接口，禁止在.c中通过extern的方式使用外部函数接口、变量。
规则1.8 禁止在extern "C"中包含头文件。

说明：在extern "C"中包含头文件，会导致extern "C"嵌套。
建议1.1 一个模块通常包含多个.c文件，建议放在同一个目录下，目录名即为模块名。为方便外部使用者，建议每一个模块提供一个.h，文件名为目录名。
建议1.2 如果一个模块包含多个子模块，则建议每一个子模块提供一个对外的.h，文件名为子模块名。

说明：降低接口使用者的编写难度。
建议1.3 头文件不要使用非习惯用法的扩展名，如.inc。
建议1.4 同一产品统一包含头文件排列方式。

2.函数

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

1.整洁函数要求：代码简单直接、不隐藏设计者的意图、用干净利落的抽象和直截了当的控制语句将函数有机组织起来。
2.代码的有效组织包括：逻辑层组织和物理层组织两个方面。逻辑层，主要是把不同功能的函数通过某种联系组织起来，主要关注模块间的接口，也就是模块的架构。物理层，无论使用什么样的目录或者名字空间等，需要把函数用一种标准的方法组织起来。例如：设计良好的目录结构、函数名字、文件组织等，这样可以方便查找。
原则2.1 一个函数仅完成一件功能。

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

如 realloc()函数情况太多，容易发生错误。

char *buffer = (char *)malloc(XXX_SIZE);// 分配内存
//.....
buffer = (char *)realloc(buffer, NEW_SIZE);// 重新分配一块内存
// 如果没有足够可用的内存用来完成重新分配，函数返回为NULL，导致buffer原来指向的内存被丢失。

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

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

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

一般情况下，可以通过提炼函数的形式消除重复代码。

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

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

过长的函数往往意味着函数功能不单一，过于复杂。函数的有效代码行数，即NBNC（非空非注释行）应当在[1，50]区间。例外：某些实现算法的函数，由于算法的聚合性与功能的全面性，可能会超过50行。
延伸阅读材料：业界普遍认为一个函数的代码行不要超过一个屏幕，避免来回翻页影响阅读；一般的代码度量工具建议都对此进行检查。

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

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

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

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;
      }
   }
}

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

说明：可重入函数是指可能被多个任务并发调用的函数。在多任务操作系统中，函数具有可重入性是多个任务可以共用此函数的必要条件。共享变量指的全局变量和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;
}

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

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

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

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

如果函数的参数比较多，而且判断的条件比较复杂（比如：一个整形数字需要判断范围等），那么冗余的代码会大面积充斥着业务代码。

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

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

示例：下面的代码导致宕机

FILE *fp = fopen( "./writeAlarmLastTime.log","r");
if(fp == NULL)
{
   
   return;
}
char buff[128] = "";
fscanf(fp,“%s”, buff); /* 读取最新的告警时间；由于文件writeAlarmLastTime.log为空，导致buff为空 */
fclose(fp);
long fileTime = getAlarmTime(buff); /* 解析获取最新的告警时间；getAlarmTime函数未检查buff指针，导致宕机 */

正确写法：

FILE *fp = fopen( "./writeAlarmLastTime.log","r");
if(fp == NULL)
{
   
   return;
}
char buff[128] = "";
if (fscanf(fp,“%s”,buff) == EOF) // 检查函数fscanf的返回值，确保读到数据,确保buff合理
{
   
   fclose(fp);
   return;
}
fclose(fp);
long fileTime = getAlarmTime(buff); //解析获取最新的告警时间；

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

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

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

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

扇入（Fan-in）和扇出（Fan-out）是Henry和Kafura在1981年引入，用来说明模块间的耦合（coupling），后面人们扩展到函数/方法、模块/类、包等。

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

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

建议2.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.2 函数应避免使用全局变量、静态局部变量和I/O操作，不可避免的地方应集中使用。

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

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

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;
}

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

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

示例：下面的代码导致宕机

hr = root_node->get_first_child(&log_item); // list.xml 为空，导致读出log_item为空
...
hr = log_item->get_next_sibling(&media_next_node); // log_item为空，导致宕机

正确写法：确保读出的内容非空。

hr = root_node->get_first_child(&log_item);
...
if (log_item == NULL) // 确保读出的内容非空=!!!!=
{
   
   return retValue;
}
hr = log_item->get_next_sibling(&media_next_node);