Recommended C Style and Coding Standards中文版全文

1 Comment

今天无意中打开了托管在Google Code上的“Recommended C Style and Coding Standards”翻译项目,忽感觉通过目录链接的方式查看译文缺少整体感,于是花了点时间将译文全文以single page的形式贴在博客里面,方便大家查看,也算是对该翻译内容的一个备份吧。

C语言编码风格和标准

0. 摘要

本文翻译自《Recommended C Style and Coding Standards》。

作者信息:

L.W. Cannon (Bell Labs)
R.A. Elliott (Bell Labs)
L.W. Kirchhoff (Bell Labs)
J.H. Miller (Bell Labs)
J.M. Milner (Bell Labs)
R.W. Mitze (Bell Labs)
E.P. Schan (Bell Labs)
N.O. Whittington (Bell Labs)
Henry Spencer (Zoology Computer Systems, University of Toronto)
David Keppel (EECS, UC Berkeley, CS&E, University of Washington)
Mark Brader (SoftQuad? Incorporated, Toronto)

本文是《Indian Hill C Style and Coding Standards》的更新版本,上面提到的最后三位作者对其进行了修改。本文主要介绍了一种C程序的推荐编码标准,内容着重于讲述编码风格,而不是功能 组织(Functional Organization)。

1. 简介

本文档修改于AT&T Indian Hill实验室内部成立的一个委员会的一份文档,旨在于建立一套通用的编码标准并推荐给Indian Hill社区。

本文主要讲述编码风格。良好的风格能够鼓励大家形成一致的代码布局,提高代码可移植性并且减少错误数量。

本文不关注功能组织,或是一些诸如如何使用goto的一般话题。我们尝试将之前的有关C代码风格的文档整合到一套统一的标准中,这套标准将适合于 任何使用C语言的工程,当然还是会有部分内容是针对一些特定系统的。另外不可避免地是这些标准仍然无法覆盖到所有情况。经验以及广泛的评价十分重 要,遇到特殊情况时,大家应该咨询有经验的C程序员,或者查看那些经验丰富的C程序员们的代码(最好遵循这些规则)。

本文中的标准本身并不是必需的,但个别机构或团体可能部分或全部采用该标准作为程序验收的一部分。因此,在你的机构中其他人很可能以一种相似的风 格编码。最终,这些标准的目的是提高可移植性,减少维护工作,尤其是提高代码的清晰度。

这里很多风格的选择都有些许武断。混合的编码风格比糟糕的编码风格更难于维护,所以当变更现有代码时,最好是保持与现有代码风格一致,而不是盲目 地遵循本文档中的规则。

"清晰的是专业的;不清晰的则是外行的" — Sir Ernest Gowers

2. 文件组织

一个文件包含的各个部分应该用若干个空行分隔。虽然对源文件没有最大长度限制,但超过1000行的文件处理起来非常不方便。编辑器很可能没有足够 的临时空间来编辑这个文件,编译过程也会因此变得十分缓慢。与回滚到前面所花费的时间相比,那些仅仅呈现了极少量信息的多行星号是不值得的,我们 不鼓励使用。超过79列的行无法被所有的终端都很好地处理,应该尽可能的避免使用。过长的行会导致过深的缩进,这常常是一种代码组织不善的症状。

2.1 文件命名惯例

文件名由一个基础名、一个可选的句号以及后缀组成。名字的第一个字符应该是一个字母,并且所有字符(除了句号)都应该是小写的字母和数字。基础名 应该由八个或更少的字符组成,后缀应该由三个或更少的字符组成(四个,如果你包含句号的话)。这些规则对程序文件以及程序使用和产生的默认文件都 适用(例如,"rogue.sav")。

一些编译器和工具要求文件名符合特定的后缀命名约定。下面是后缀命名要求:

    C源文件的名字必须以.c结尾
    汇编源文件的名字必须以.s结尾

我们普遍遵循以下命名约定:

    可重定位目标文件名以.o结尾
    头文件名以.h结尾
        在多语言环境中一个可供选择的更好的约定是用语言类型和.h共同作为后缀(例如,"foo.c.h" 或 "foo.ch")。

    Yacc源文件名以.y结尾
    Lex源文件名以.l结尾

C++使用编译器相关的后缀约定,包括.c,..c,.cc,.c.c以及.C。由于大多C代码也是C++代码,因此这里并没有一个明确的方案。

此外,我们一般约定使用"Makefile"(而不是"makefile")作为make(对于那些支持make的系统)工具的控制文件,并且使 用"README"作为简要描述目录内容或目录树的文件。

2.2 程序文件

下面是一个程序文件各个组成部分的推荐排列顺序:

文件的第一部分是一个序,用于说明该文件中的内容是什么。对文件中的对象(无论它们是函数,外部数据声明或定义,或是其他一些东西)用途的描述比 一个对象名字列表更加有用。这个序可选择地包含作者信息、修订控制信息以及参考资料等。

接下来是所有被包含的头文件。如果某个头文件被包含的理由不是那么显而易见,我们需要通过增加注释说明原因。大多数情况下,类似stdio.h这 样的系统头文件应该被放在用户自定义头文件的前面。

接下来是那些用于该文件的defines和typedefs。一个常规的顺序是先写常量宏、再写函数宏,最后是typedefs和枚举 (enums)定义。

接下来是全局(外部)数据声明,通常的顺序如下:外部变量,非静态(non-static)全局变量,静态全局变量。如果一组定义被用于部分特定 全局数据(如一个标志字),那么这些定义应该被放在对应数据声明后或嵌入到结构体声明中,并将这些定义缩进到其应用的声明的第一个关键字的下一个 层次(译注:实在没有搞懂后面这句的含义)。

最后是函数,函数应该以一种有意义的顺序排列。相似的函数应该放在一起。与深度优先(函数定义尽可能在他们的调用者前后)相比,我们应该首选广度 优先方法(抽象层次相似的函数放在一起)。这里需要相当多的判断。如果定义大量本质上无关的工具函数,可考虑按字母表顺序排列。

2.3 头文件

头文件是那些在编译之前由C预处理器包含在其他文件中的文件。诸如stdio.h的一些头文件被定义在系统级别,所有使用标准I/O库的程序必须 包含它们。头文件还用来包含数据声明和定义,这些数据不止一个程序需要。头文件应该按照功能组织,例如,独立子系统的声明应该放到独立的头文件 中。如果一组声明在代码从一种机器移植到另外一种机器时变动的可能性很大,那么这些声明也应该被放在独立的头文件中。

避免私有头文件的名字与标准库头文件的名字一样。下面语句:

#include "math.h"

当预期的头文件在当前目录下没有找到时,它将会包含标准库中的math头文件。如果这的确是你所期望发生的,那么请加上注释。包含头文件时不要使 用绝对路径。当从标准位置获取头文件时,请使用<name>包含头文件;或相对于当前路径定义它们。C编译器的"include- path"选项(在许多系统中为-l)是处理扩展私有库头文件的最好方法,它允许在不改变源码文件的情况下重新组织目录结构。

声明了函数或外部变量的头文件应该被那些定义了这些函数和变量的文件所包含。这样一来,编译器就可以做类型检查了,并且外部声明将总是与定义保持 一致。

在头文件中定义变量往往是个糟糕的想法,它经常是一个在文件间对代码进行低劣划分的症状。此外,在一次编译中,像typedef和经过初始化的数 据定义无法被编译器看到两次。在一些系统中,重复的没有使用extern关键字修饰的未初始化定义也会导致问题。当头文件嵌套时,会出现重复的声 明,这将导致编译失败。

头文件不应该嵌套。一个头文件的序应该描述其使用的其他被包含的头文件的实用特性。在极特殊情况下,当大量头文件需要被包含在多个不同的源文件中 时,可以被接受的做法是将公共的头文件包含在一个单独的头文件中。

一个通用的做法是将下面这段代码加入到每个头文件中以防止头文件被意外多次包含。

#ifndef EXAMPLE_H
#define EXAMPLE_H
 …    /* body of example.h file */
#endif /* EXAMPLE_H */

我们不应该对这种避免多次包含的机制产生依赖,特别是不应该因此而嵌套包含头文件。

2.4 其他文件

还有一个惯例就是编写一个名为"README"的文件,用于描述程序的整体情况以及问题。例如,我们经常在README包含程序所使用的条件编译 选项列表以及相关说明,还可以包含机器无关的文件列表等。

4. 声明

全局声明应该从第一列开始。在所有外部数据声明的前面都应该放置extern关键字。如果一个外部变量是一个在定义时大小确定的数组,那么这个数 组界限必须在extern声明时显示指出,除非数组的大小与数组本身编码在一起了(例如,一个总是以0结尾的只读字符数组)。重复声明数组大小对 于一些使用他人编写的代码的人特别有益。

指针修饰符*应该与变量名在一起,而不是与类型在一起。

char  *s, *t, *u;

替换

char*  s, t, u;

后者是错误的,因为实际上t和u并未如预期那样被声明为指针。

不相关的声明,即使是相同类型的,也应该独立占据一行。我们应该对声明对象的角色进行注释,不过当常量名本身足以说明角色时,使用#define 定义的常量列表则不需要注释。通常多行变量名、值与注释使用相同缩进,使得他们在一列直线上。尽量使用Tab字符而不是空格。结构体和联合体的声 明时,每个元素应该单独占据一行,并附带一条注释。{应该与结构体的tag名放在同一行,}应该放在声明结尾的第一列。

struct boat {
    int    wllength;    /* water line length in meters */
    int    type;        /* see below */
    long   sailarea;    /* sail area in square mm */
};

/* defines for boat.type */
#define    KETCH    (1)
#define    YAWL     (2)
#define    SLOOP    (3)
#define    SQRIG    (4)
#define    MOTOR    (5)

这些defines有时放在结构体内type声明的后面,并使用足够的tab缩进到结构体成员成员的下一级。如果这些实际值不那么重要的话,使用 enum会更好。

enum bt { KETCH=1, YAWL, SLOOP, SQRIG, MOTOR };
struct boat {
    int     wllength;    /* water line length in meters */
    enum bt type;        /* what kind of boat */
    long    sailarea;    /* sail area in square mm */
};

任何初值重要的变量都应该被显式地初始化,或者至少应该添加注释,说明依赖C的默认初始值0。空初始化"{}"应该永远不被使用。结构体初始化应 该用大括号完全括起来。用于初始化长整型(long)的常量应该使用显式长度。使用大写字母,例如2l看起来更像21,数字二十一。

int   x = 1;
char  *msg = "message";
struct boat    winner[] = {
    { 40, YAWL, 6000000L },
    { 28, MOTOR, 0L },
    { 0 },
};

如果一个文件不是独立程序,而是某个工程整体的一部分,那么我们应该最大化的利用static关键字,使得函数和变量对于单个文件来说是局部范畴 的。只有在有清晰需求且无法通过其他方式实现的特殊情况时,我们才允许变量被其他文件访问。这种情况下应该使用注释明确告知使用了其他文件中的变 量;注释应该说明其他文件的名字。如果你的调试器遮蔽了你需要在调试阶段查看的静态对象,那么可以将这些变量声明为STATIC,并根据需要决定 是否#define STATIC。

最重要的类型应该被typedef,即使他们只是整型,因为独立的名字使得程序更加易读(如果只有很少的几个integer的typedef)。 结构体在声明时应该被typedef。保持结构体标志的名字与typedef后的名字相同。

typedef struct splodge_t {
    int  sp_count;
    char *sp_name, *sp_alias;
} splodge_t;

总是声明函数的返回类型。如果函数原型可用,那就使用它。一个常见的错误就是忽略那些返回double的外部数学函数声明。那样的话,编译器就会 假定这些函数的返回值为一个整型数,并且将bit位逐一尽职尽责的注意转换为一个浮点数(无意义)。

"C语言的观点之一是程序员永远是对的" — Michael DeCorte

5. 函数声明

每个函数前面应该放置一段块注释,概要描述该函数做什么以及(如果不是很清晰)如何使用该函数。重要的设计决策讨论以及副作用说明也适合放在注释 中。避免提供那些代码本身可以清晰提供的信息。

函数的返回类型应该单独占据一行,(可选的)缩进一个级别。不用使用默认返回类型int;如果函数没有返回值,那么将返回类型声明为void。如 果返回值需要大段详细的说明,可以在函数之前的注释中描述;否则可以在同一行中对返回类型进行注释。函数名(以及形式参数列表)应该被单独放在一 行,从第一列开始。目的(返回值)参数一般放在第一个参数位置(从左面开始)。所有形式参数声明、局部声明以及函数体中的代码都应该缩进一级。函 数体的开始括号应该单独一行,放在开始处的第一列。

每个参数都应该被声明(不要使用默认类型int)。通常函数中每个变量的角色都应该被描述清楚,我们可以在函数注释中描述,或如果每个声明单独一 行,我们可以将注释放在同一行上。像循环计数器"i",字符串指针"s"以及用于标识字符的整数类型"c"这些简单变量都无需注释。如果一组函数 都拥有一个相似的参数或局部变量,那么在所有函数中使用同一个名字来标识这个变量是很有益处的(相反,避免在相关函数中使用一个名字标识用途不同 的变量)。不同函数中的相似参数还应该放在各个参数列表中的相同位置。

参数和局部变量的注释应该统一缩进以排成一列。局部变量声明应用一个空行与函数语句分隔开来。

当你使用或声明变长参数的函数时要小心。目前在C中尚没有真正可移植的方式处理变长参数。最好设计一个使用固定个数参数的接口。如果一定要使用变 长参数,请使用标准库中的宏来声明具有变长参数的函数。

如果函数使用了在文件中没有进行全局声明的外部变量(或函数),我们应该在函数体内部使用extern关键字单独对这些变量进行声明。

避免局部声明覆盖高级别的声明。尤其是,局部变量不应该在嵌套代码块中被重声明。虽然这在C中是合法的,但是当使用-h选项时,潜在的冲突可能性 足以让lint工具发出抱怨之声。

6. 空白

int i;main(){for(;i["] o, world!\n",'/'/'/'));}read(j,i,p){write(j/p+p,i—j,i/i);}
- 不光彩的事情,模糊C代码大赛,1984年。作者要求匿名。

通常情况下,请使用纵向和横向的空白。缩进和空格应该反映代码的块结构。例如,在一个函数定义与下一个函数的注释之间,至少应该有两行空白。

如果一个条件分支语句过长,那就应该将它拆分成若干单独的行。

if (foo->next==NULL && totalcount<needed && needed<=MAX_ALLOT
    && server_active(current_input)) { …

也许下面这样更好

if (foo->next == NULL
    && totalcount < needed && needed <= MAX_ALLOT
    && server_active(current_input))
{
    …

类似地,复杂的循环条件也应该被拆分为不同行。

for (curr = *listp, trail = listp;
    curr != NULL;
    trail = &(curr->next), curr = curr->next )
{
    …

其他复杂的表达式,尤其是那些使用了?:操作符的表达式,最好也能拆分成多行。

c = (a == b)
    ? d + f(a)
    : f(b) – d;

当关键字后面有放在括号内的表达式时,应该使用空格将关键字与左括号分隔(sizeof操作符是个例外)。在参数列表中,我们也应该使用空格显式 的将各个参数隔开。然而,带有参数的宏定义一定不能在名字与左括号间插入空格,否则C预编译器将无法识别后面的参数列表。

7. 例子

        /*
     * Determine if the sky is blue by checking that it isn't night.
     * CAVEAT: Only sometimes right.  May return TRUE when the answer
     * is FALSE.  Consider clouds, eclipses, short days.
     * NOTE: Uses 'hour' from 'hightime.c'.  Returns 'int' for
     * compatibility with the old version.
     */
    int  /* true or false */
    skyblue()
    {
        extern int hour;   /* current hour of the day */

        return (hour >= MORNING && hour <= EVENING);
    }

    /*
     * Find the last element in the linked list
     * pointed to by nodep and return a pointer to it.
     * Return NULL if there is no last element.
     */
    node_t *
    tail(nodep)
    node_t  *nodep;     /* pointer to head of list */
    {
       register node_t *np; /* advances to NULL */
       register node_t *lp; /* follows one behind np */

       if (nodep == NULL)
            return (NULL);
       for (np = lp = nodep; np != NULL; lp = np, np = np->next)
            ;       /* VOID */
       return (lp);
    }

8. 简单语句

每行只应该有一条语句,除非多条语句关联特别紧密。

case FOO:  oogle (zork);  boogle (zork);  break;
case BAR:  oogle (bork);  boogle (zork);  break;
case BAZ:  oogle (gork);  boogle (bork);  break;

for或while循环语句的空体应该单独放在一行并加上注释,这样可以清晰的看出空体是有意而为,并非遗漏代码。

while (*dest++ = *src++)
    ;    /* VOID */

不要对非零表达式进行默认测试,例如:

if (f() != FAIL)

比下面的代码更好

if (f())

即使FAIL的值可能为0(在C中0被认为是假)。当后续有人决定使用-1替代0作为失败返回值时,一个显式的测试将解决你的问题。即使比较的值 永远不会改变,我们也应该使用显式的比较;例如

if (!(bufsize % sizeof(int)))

应该被写成

if ((bufsize % sizeof(int)) == 0)

这样可以反映这个测试的数值(非布尔)本质。一个常见的错误点是使用strcmp测试字符串是否相同,这个测试的结果永远不应该被放弃。比较好的 方法是定义一个宏STREQ。

#define STREQ(a, b) (strcmp((a), (b)) == 0)

对谓词或满足下面约束的表达式,非零测试经常被放弃:

    0表示假,其他都为真。
    通过其命名可以看出返回真是显而易见的。

用isvalid或valid称呼一个谓词,不要用checkvalid。

一个非常常见的实践就是在一个全局头文件中声明一个布尔类型"bool"。这个特殊的名字可以极大地提高代码可读性。

typedef int    bool;
#define FALSE    0
#define TRUE    1

typedef enum { NO=0, YES } bool;

即便有了这些声明,也不要检查一个布尔值与1(TRUE,YES等)的相当性;可用测试与0(FALSE,NO等)的不等性替代。绝大多数函数都 可以保证为假的时候返回0,但为真的时候只返回非零。

if (func() == TRUE) { …

必须被写成

if (func() != FALSE) { …

如果可能的话,最好为函数/变量重命名或者重写这个表达式,这样就可以显而易见的知道其含义,而无需再与true或false比较了(例如,重命 名为isvalid())。

嵌入赋值语句也有用武之地。在一些结构中,在没有降低代码可读性的前提下,没有比这更好的方式来实现这个结果了。

while ((c = getchar()) != EOF) {
    process the character
}

++和–操作符可算作是赋值语句。这样,为了某些意图,实现带有副作用的功能。使用嵌入赋值语句也可能提高运行时的性能。不过,大家应该在提高 的性能与下降的可维护性之间做好权衡。当在一些人为的地方使用嵌入赋值语句时,这种情况会发生,例如:

a = b + c;
d = a + r;

不应该被下面代码替代:

d = (a = b + c) + r;

即使后者可能节省一个计算周期。在长期运行时,由于优化器渐获成熟,两者的运行时间差距将下降,而两者在维护性方面的差异将提高,因为人类的记忆 会随着时间的流逝而衰退。

在任何结构良好的代码中,goto语句都应该保守地使用。使用goto带来好处最大的地方是从switch、for和while多层嵌套中跳出, 但这样做的需求也暗示了代码的内层结构应该被抽取出来放到一个单独的返回值为成功或失败的函数中。

    for (…) {
        while (…) {
            …
            if (disaster)
                goto error;

        }
    }
    …
error:
    clean up the mess

当需要goto时候,其对应的标签应该被放在单独一行,并且后续的代码缩进一级。使用goto语句时应该增加注释(可能放在代码块的头)以说明它 的功用和目的。continue应该保守地使用,并且尽可能靠近循环的顶部。Break的麻烦比较少。

非原型函数的参数有时需要被显式做类型提升。例如,如果函数期望一个32bit的长整型,但却被传入一个16bit的整型数,可能会导致函数栈不 对齐。指针,整型和浮点值都会发生此问题。

9. 复合语句

复合语句是一个由括号括起来的语句列表。有许多种常见的括号格式化方式。如果你有一个本地标准,那请你与本地标准保持一致,或选择一个标准,并持 续地使用它。在编辑别人的代码时,始终使用那些代码中使用的样式。

control {
       statement;
       statement;
}

上面的风格被称为"K&R风格",如果你还没有找到一个自己喜欢的风格,那么可以优先考虑这个风格。在K&R风格中,if- else语句中的else部分以及do-while语句中的while部分应该与结尾大括号在同一行中。而其他大部分风格中,大括号都是单独占据 一行的。

当一个代码块拥有多个标签时,每个标签应该单独放在一行上。必须为C语言的switch语句的fall-through特性(即在代码段与下一个 case语句之前间没有break)增加注释以利于后期更好的维护。最好是lint风格的注释/指示。

switch (expr) {
case ABC:
case DEF:
     statement;
    break;
case UVW:
     statement;
     /*FALLTHROUGH*/
case XYZ:
    statement;
    break;
}

这里,最后那个break是不必要的,但却是必须的,因为如果后续另外一个case添加到最后一个case的后面时,它将阻止fall- through错误的发生。如果使用default case,那么应该该default case放在最后,且不需要break,如果它是最后一个case。

一旦一个if-else语句在if或else段中包含一个复合语句,if和else两个段都应该用括号括上(称为全括号(fully bracketed)语法)。

if (expr) {
    statement;
} else {
    statement;
    statement;
}

在如下面那样的没有第二个else的if-if-else语句序列里,括号也是不必可少的。如果ex1后面的括号被省略,编译器解析将出错:

if (ex1) {
    if (ex2) {
         funca();
    }
} else {
    funcb();
}

一个带else if的if-else语句在书写上应该让else条件左对齐。

if (STREQ (reply, "yes")) {
    statements for yes
    …
} else if (STREQ (reply, "no")) {
    …
} else if (STREQ (reply, "maybe")) {
    …
} else {
    statements for default
    …
}

这种格式看起来像一个通用的switch语句,并且缩进反映了在这些候选语句间的精确切换,而不是嵌套的语句。

Do-while循环总是使用括号将循环体括上。

下面的代码非常危险:

#ifdef CIRCUIT
#    define CLOSE_CIRCUIT(circno) { close_circ(circno); }
#else
#    define CLOSE_CIRCUIT(circno)
#endif


if (expr)
    statement;
else
    CLOSE_CIRCUIT(x)
++i;

注意,在CIRCUIT没有定义的系统上,语句++i仅仅在expr是假的时候获得执行。这个例子指出宏用大写命名的价值,以及让代码完全括号化 的价值。

有些时候,通过break,continue,goto或return,if可以无条件地进行控制转移。else应该是隐式的,并且代码不应该缩 进。

if (level > limit)
    return (OVERFLOW)
normal();
return (level);

平坦的缩进告诉读者布尔测试在密封块的其他部分是保持不变的。

10. 操作符

一元操作符不应该与其唯一的操作数分开。通常,所有其他二元操作符都应该使用空白与其操作树分隔开,但'.'和'->'例外。当遇到复杂表 达式的时候我们需要做出一些判断。如果内层操作符没有使用空白分隔而外层使用了,那么表达式也许会更清晰些。

如果你认为一个表达式很难于阅读,可以考虑将这个表达式拆分为多行。在接近中断点的最低优先级操作符处拆分是最好的选择。由于C具有一些想不到的 优先级规则,混合使用操作符的表达式应该使用括号括上。但是过多的括号也会使得代码可读性变差,因为人类不擅长做括号匹配。

二元逗号操作符也会被使用到,但通常我们应该避免使用它。逗号操作符的最大用途是提供多元初始化或操作,比如在for循环语句中。复杂表达式,例 如那些使用了嵌套三元?:操作符的表达式,可能引起困惑,并且应该尽可能的避免使用。三元操作符和逗号操作符在一些使用宏的地方很有用,诸如 getchar。在三元操作符?:前的逻辑表达式的操作数应该被括起来,并且两个子表达式的返回值应该是相同类型。

11. 命名约定

毫无疑问,每个独立的工程都有一套自己的命名约定,不过仍然有一些通用的规则值得参考。

    * 为系统用途保留以下划线开头或下划线结尾的名字,并且这些名字不应该被用在任何用户自定义的名字中。大多数系统使用这些名字用于用户不应 该也不需知道的名字中。如果你一定要使用你自己私有的标识符,可以用标识它们归属的包的字母作为开头。

    * #define定义的常量名字应该全部大写。

    * Enum常量应该大写或全部大写。

    * 函数名、typedef名,变量名以及结构体、联合体与枚举标志的名字应该用小写字母。

    * 很多"宏函数"都是全部大写的。一些宏(诸如getchar和putchar)使用小写字母命名,这事因为他们可能被当成函数使用。只有在宏的行为类似一 个函数调用时才允许小写命名的宏,也就是说它们只对其参数进行一次求值,并且不会给具名形式参数赋值。有些时候我们无法编写出一个具有函数行为的 宏,即使其参数也只是求值一次。

    * 避免在同一情形下使用不同命名方式,比如foo和Foo。同样避免foobar和foo_bar这种方式。需要考虑这样所带来的困惑。

    * 同样,避免使用看起来相似的名字。在很多终端以及打印设备上,'I'、'1'和'l'非常相似。给变量命名为l特别糟糕,因为它看起来十分像常量'1'。

通常,全局名字(包括enum)应该具有一个统一的前缀,通过该前缀名我们可以识别出这个名字归属于哪个模块。全局变量可以选择汇集在一个全局结 构中。typedef的名字通常在结尾加一个't'。

避免名字与各种标准库中的名字冲突。一些系统可能包含一些你所不需要的库。另外你的程序将来某天很可能也要扩展。

12. 常量

数值型常量不应该被硬编码到源文件中。应该使用C预处理器的#define特性为常量赋予一个有意义的名字。符号化的常量可以让代码具有更好的可 读性。在一处地方统一定义这些值也便于进行大型程序的管理,这样常量值可以在一个地方进行统一修改,只需修改define的值即可。枚举数据类型 更适合声明一组具有离散值的变量,并且编译器还可以对其进行额外的类型检查。至少,任何硬编码的值常量必须具有一段注释,以说明该值的来历。

常量的定义应该与其使用是一致的;例如使用540.0作为一个浮点数,而不是使用540外加一个隐式的float类型转换。有些时候常量0和1被 直接使用而没有用define进行定义。例如,一个for循环语句中用于标识数组下标的常量,

for (i = 0; i < ARYBOUND; i++)

上面代码是合理的,但下面代码

door_t *front_door = opens(door[i], 7);
if (front_door == 0)
    error("can't open %s\\\\n", door[i]);

是不合理的。在最后的那个例子中,front_door是一个指针。当一个值是指针的时候,它应该与NULL比较而不是与0比较。NULL被定义 在标准I/O库头文件stdio.h中,在一些新系统中它在stdlib.h中定义。即使像1或0这样的简单值,我们最好也用define定义成 TRUE和FALSE定义后再使用(有些时候,使用YES和NO可读性更好)。

简单字符常量应该被定义成字面值,不应该使用数字。不鼓励使用非可见文本字符,因为它们是不可移植的。如果非可见文本字符十分必要,尤其是当它们 在字符串中使用时,它们应该定义成三个八进制数字的转义字符(例如: '\007‘)而非一个字符。即使这样,这种用法也应该考虑其机器相关性,并按这里的方法处理。

13. 宏

复杂表达式可能会被用作宏参数,这可能会因操作符优先级顺序而引发问题,除非宏定义中所有参数出现的位置都用括号括上了。对这种因参数内副作用而 引发的问题,我们似乎也无能为例,除了在编写表达式时杜绝副作用(无论如何,这都是一个很好的主意)。如果可能的话,尽量在宏定义中对宏参数只进 行一次求值。有很多时候我们无法写出一个可像函数一样使用的宏。

一些宏也当成函数使用(例如,getc和fgetc)。这些宏会被用于实现其他函数,这样一旦宏自身发生变化,使用该宏的函数也会受到影响。在交 换宏和函数时务必要小心,因为函数参数是按值传递的,而宏参数则是通过名称替换。只有在宏定义时特别谨慎小心,才有可能减少使用宏时的担心。

宏定义中应该避免使用全局变量,因为全局变量的名字很可能被局部声明遮盖。对于那些对具名参数进行修改(不是这些参数所指向的存储区域)或被用作 赋值语句左值的宏,我们应该添加相应的注释以给予提醒。那些不带参数但引用变量,或过长或作为函数别名的宏应该使用空参数列表,例如:

#define    OFF_A()    (a_global+OFFSET)
#define    BORK()    (zork())
#define    SP3()    if (b) { int x; av = f (&x); bv += x; }

宏节省了函数调用和返回的额外开销,但当一个宏过长时,函数调用和返回的额外开销就变得微不足道了,这种情况下我们应该使用函数。

在一些情况下,让编译器确保宏在使用时应该以分号结尾是很有必要的。

if (x==3)
    SP3();
else
    BORK();

如果省略SP3调用后面的分号,后面的else将会匹配到SP3宏中的那个if。有了分号,else分支就不会与任何if匹配。SP3宏可以这样 安全地实现:

#define SP3() \\\\
     do { if (b) { int x; av = f (&x); bv += x; }} while (0)

手工给宏定以加上do-while包围看起来很别扭,而且很多编译器和工具会抱怨在while条件是一个常量值。一个用来声明语句的宏可以使得编 码更加容易:

#ifdef lint
    static int ZERO;
#else
#    define ZERO 0
#endif
#define STMT( stuff ) do { stuff } while (ZERO)

我们可以用下面代码来声明SP3宏:

#define SP3() \\\\
    STMT( if (b) { int x; av = f (&x); bv += x; } )

使用STMT宏可以有效阻止一些可以潜在改变程序行为的打印排版错误。

除了类型转换、sizeof以及上面那些技巧和手法,只有当整个宏用括号括上时才应该包含关键字。

14. 条件编译

条件编译在处理机器依赖、调试以及编译阶段设定特定选项时十分有用。不过要小心条件编译。各种控制很容易以一种无法预料的方式结合在一起。如果使 用#ifdef判断机器依赖,请确保当没有机器类型适配时,返回一个错误,而不是使用默认机器类型(使用#error并缩进一级,这样它可以一些老旧的编 译器下工作)。如果你#ifdef优化选项,默认情况下应该是一个未经优化的代码,而不是一个不兼容的程序。确保测试的是未经优化的代码。

注意在#ifdef区域内的文本可能会被编译器扫描(处理),即使#ifdef求值的结果为假。但即使文件的#ifdef部分永远不能被编译到(例如,#ifdef COMMENT),这部分也不该随意的放置文本。

尽可能地将#ifdefs放在头文件中,而不是源文件中。使用#ifdef定义可以在源码中统一使用的宏。例如,一个用于检查内存分配的头文件可能这样实现:(省略了REALLOC和FREE):

#ifdef DEBUG
    extern void *mm_malloc();
#    define MALLOC(size) (mm_malloc(size))
#else
    extern void *malloc();
#    define MALLOC(size) (malloc(size))
#endif

条件编译通常应该基于一个接一个的特性的。多数情况下,都应该避免使用机器或操作系统依赖。

#ifdef BSD4
    long t = time ((long *)NULL);
#endif

上面代码之所以糟糕有两个原因:很可能在某个4BSD系统上有更好的选择,并且也可能存在在某个非4BSD系统中上述代码是最佳代码。我们可以通过定义诸 如TIME_LONG和TIME_STRUCTD等宏作为替代,并且在诸如config.h的配置文件中定义一个合适的宏。

16. 可移植性

    "C语言结合了汇编的强大功能和可移植性" — 无名氏,暗指比尔.萨克。

可移植代码的好处是有目共睹的。这一节将阐述一些编写可移植代码的指导原则。这里"可移植的"是指一个源码文件能够在不同机器上被编译和执行,其 前提仅仅是在不同平台上可能包含不同的头文件,使用不同的编译器开关选项罢了。头文件包含的#define和typedef可能因机器而异。一般 来说,一个新"机器"是指一种不同的硬件,一种不同的操作系统,一个不同的编译器,或者是这些的任意组合。参考1包含了很多关于风格和可移植 性方面的有用信息。下面是一个隐患列表,当你设计可移植代码时应该考虑避免这些隐患:

    * 编写可移植的代码。只有当被证明是必要的情况下才考虑优化的细节。优化后的代码往往是模糊不清、难以理解的。在一台机器上经过优化后的代码,在其他机器上 可能变得更加糟糕。将采用的性能优化手段记录下来并尽可能多地本地化。文档应该解释这些手段的工作原理以及引入它们的原因(例如:"循环执行了无 数次")

    * 要意识到很多东西天生就是不可移植的。比如处理类似程序状态字这样的特定硬件寄存器的代码,以及被设计用于支持某特定硬件部件的代码,诸如汇编器以及 I/O驱动。即使在这种情况下,许多例程和数据仍然可以被设计成机器无关的。

    * 组织源文件时将机器无关与机器相关的代码分别放在不同文件中。之后如果这个程序需要被移植到一个新机器上时,我们就可以很容易判断出来哪些需要被改变。为 一些文件的头文件中机器依赖相关的代码添加注释。

    * 任何"实现相关"的行为都应该作为机器(编译器)依赖对待。假设编译器或硬件以一种十分古怪的方式实现它。

    * 注意机器字长。对象的大小可能不直观,指针大小也不总是与整型大小相同,也不总是彼此大小相同,或者可相互自由转换。下面的表中列举了C语言基本类型在不 同机器和编译器下的大小(以bit为单位)。

type    pdp11  VAX/11 68000  Cray-2 Unisys Harris 80386
        series       family          1100   H800
char     8      8      8       8      9     8      8
short    16    16     8/16   64(32)   18    24    8/16
int      16    32     16/32  64(32)   36    24    16/32
long     32    32      32    64       36    48    32
char*    16    32      32    64       72    24    16/32/48
int*     16    32      32    64(24)   72    24    16/32/48
int(*)() 16    32      32    64       576   24    16/32/48

有些机器针对某一类型可能有不止一个大小。其类型大小取决于编译器和不同的编译期标志。下面表展示了大多数系统的"安全"类型大小。无符号与带符 号数具有相同的大小(单位:bit)。

Type    Minimum  No Smaller
          # Bits   Than
char       8  
short      16    char
int        16    short
long       32    int
float      24  
double     38    float
any *      14  
char *     15    any *
void *     15    any *

    * void类型可以保证有足够位精度来表示一个指向任意数据对象的指针。void()()类型可以保证表示一个指向任意函数的指针。当你需要通用指针时 可以使用这些类型(在一些旧的编译器里,分别用char和char()()表示)。确保在使用这些指针类型之前将其转换回正确的类型。

    * 即使说一个int和一个char类型大小相同,它们仍可能具有不同的格式。例如,下面例子在一些sizeof(int)等于 sizeof(char)的机器上可能失败。其原因在与free函数期望一个char,但却传入了一个int。

    int *p = (int *) malloc (sizeof(int));
   free (p);

    * 注意,一个对象的大小不能保证这个对象的精度。Cray-2可能使用64位来存储一个整型,但一个长整型转换为一个整型并且再转换回长整型后可能会被截断 为32位。

    * 整型常量0可以强制转型为任何指针类型。转换后的指针称为对应那个类型的空指针,并且与那个类型的其他指针不同。空指针比较总是与常量0相当。空指针不应 该与一个值为0的变量比较。空指针不总是使用全0的位模式表示。两个不同类型的空指针有些时候可能不同。某个类型的空指针被强制转换为另外一个类 型的指针,其结果是该指针转换为第二个类型的空指针。

    * 对于ANSI编译器,当两个类型相同的指针访问同一块存储区时,则它们比较是相等的。当一个非0整型常量被转换为指针类型时,它们可能与其他指针相等。对 于非ANSI编译器,访问同一块存储区的两个指针比较可能并不相同。例如,下面两个指针比较可能相等或不相等,并且他们可能或可能没有访问同一块 存储区域。

    ((int *) 2 )
    ((int *) 3 )

如果你需要'magic'指针而不是NULL,要么分配一些内存,要么将指针视为机器相关的。

extern int x_int_dummy;    /* in x.c */
#define X_FAIL    (NULL)
#define X_BUSY    (&x_int_dummy)
#define X_FAIL    (NULL)
#define X_BUSY    MD_PTR1  /* MD_PTR1 from "machdep.h" */

    * 浮点数字既包含精度也包含范围。这些都是数据对象大小无关的。但是,一个32位浮点数在不同机器上溢出时的值有所不同。同时,4.9乘以5.1在不同的机 器上可能产生两个不同的数字。在圆整(rounding)和截断方面的差异将给出特别不同的答案。

    * 在一些机器上,一个双精度浮点数在精度或范围方面可能比一个单精度浮点数还要低。

    * 在一些机器上,double值的前半部分可能是一个具有相同值的float类型。千万不要依赖于此。

    * 提防带符号字符。例如,在某些VAX系统上,用在表达式中的字符是符号扩展的,但在其他一些机器上并非如此。对有符号和无符号有依赖的代码是不可移植的。 例如,如果假设c是正值,arrayc在c为有符号且为负值时将无法正常工作。如果你一定要假设signed或unsigned字符的话,请 用SIGNED或UNSIGNED为其加上注释。无符号字符的行为可由unsigned char保证。

    * 避免对ASCII做假设。如果你必须假设,那么请将其记录下来并本地化。请记住字符很可能用不止8位表示。

    * 大多数机器采用2的补码表示数,但我们在代码中不应该利用这一特点。使用等价移位操作替代算术运算的优化尤其值得怀疑。如果必须这么做,那么机器相关的代 码应该用#ifdef定义,或者操作应该在#ifdef宏判定下执行。你应该衡量一下使用这种难以理解的代码所节省的时间与做代码移植时找bug 所花费的时间相比孰多孰少。

    * 一般情况下,如果字长或值范围非常重要,应该使用typedef定义具有特定大小的类型。大型程序应该具有一个统一的头文件用于提供通用的、大小 (size)敏感的类型的typedef定义,这样更加便于修改以及在紧急修复时查找大小敏感的代码。无符号类型比有符号整型更加编译器无关。如 果既可以用16bit也可以用32bit标识一个简单for循环的计数器,我们应该使用int。因为对于当前机器来说,通过整型可以获取更高效 (自然)的存储单元。

    * 数据对齐也很重要。例如,在不同的机器上,一个四字节的整型数的可能以任意地址作为起始地址,也可能只允许以偶数地址作为起始地址,或者只能以4的整数倍 的地址作为起始地址。因此,一个特定的结构体的各个元素在不同的机器上的偏移量有不同,即使给定的这些元素在所有机器上的大小相同。事实上,一个 包含一个32位指针和一个8位字符的结构提在三个不同的机器上可能有三个不同的大小。作为一个推论,对象指针可能无法自由互换;通过一个指向起始 地址为奇数地址长度为4个字节的指针保存一个整型数有时可以正常工作,但有时则会导致产生core,有些时候静悄悄地失败了(在这个过程中会破坏 其他数据)。在那些不按字节寻址的机器上,字符指针更是"事故高发地区"。对齐考虑以及加载器的特殊性使得很容易轻率地认为两个连续声明的变量在 内存中也是连在一起的,或者某个类型的变量已经被适当对齐并可以用作其他类型变量使用了。

    * 在一些机器上,诸如VAX(小端),一个字的字节随着地址的增加,其重要性提高;而另外一些机器上,诸如68000(大端),随着地址的增加,其重要性降 低。字或更大数据对象(诸如一个双精度字)的字节顺序可能并不相同。因此,任何依赖对象内从左到右方向位模式的代码都值得特别细致的审查。只有当 结构体中两个不同的位字段不被连接以及不被当作一个单元时,这些位字段才具备可移植性。事实上,连接任意两个变量都是不可移植的行为。

    * 结构体中有一些未使用的空洞。猜想联合体用于类型欺骗。尤其是,一个值不应该在存储时使用一个类型,而在读取时使用另外一种类型。对联合体来说,一个显式 的标签(tag)字段可能会很有用。

    * 不同的编译器在返回结构体时使用不同的约定。这就会导致代码在接受从不同编译器编译的库代码中返回的结构体值时会出现错误。结构体指针不是问题。

    * 不要假设参数传递机制。特别是指针大小以及参数求值顺序,大小等。例如,下面的代码就不具备可移植性。

        c = foo (getchar(), getchar());

    char
    foo (c1, c2, c3)
    char c1, c2, c3;
    {
        char bar = *(&c1 + 1);
        return (bar);            /* often won't return c2 */
    }

    * 上面的例子有诸多问题。栈可能向上增长,也可能向下增长(事实上,甚至都不需要一个栈)。参数在传入时可能被扩大,例如一个char可能以int型被传 入。参数可能以从左到右,从右到左,或以任意顺序压入栈,或直接放在寄存器中(根本无需压栈)。参数求值的顺序也可能与压栈的次序有所不同。一个 编译器可能使用多种(不兼容的)调用约定。

    * 在某些机器上,空字符指针((char *)0)常被当作指向空字符串的指针对待。不要依赖于此。

   *  不要修改字符串常量。下面就是一个臭名昭著的例子

    s = "/dev/tty??";
  strcpy (&s[8], ttychars);

    * 地址空间可能有空洞。简单计算一个数组中未分配空间的元素(在数组实际存储区域之前或之后)的地址可能会导致程序崩溃。如果这个地址被用于比较,有时程序 可以运行,但会破坏数据,报错,或陷入死循环。在ANSI C中,指向一个对象数组的指针指向数组结尾后的第一个元素是合法的,这在一些老编译器上通常是安全的。不过这个"在外边"不可以被解引用。

    * 只有==和!=比较可用于某给定类型的所有指针。当两个指针指向同一个数组内的元素(或数组后第一个元素)时,使用<<、<=、& amp; gt;或>=对两个指针进行比较是可移植的。同样,仅仅对指向同一个数组内的元素(或数组后第一个元素)的两个指针使用算术操作符才是可移 植的。

    * 字长(word size)也影响移位和掩码。下面代码在一些68000机器上只会将一个整型数的最右三个位清0,而在其他机器上它还会将高地址的两个字节清零。x &= 0177770 使用 x &= ~07可以在所有机器上正常工作。位字段(bitfield)没有这些问题。

    * 表达式内的副作用可能导致代码语义是编译器相关的,因为在大多数情况下C语言的求值顺序是没有显式定义的。下面是一个臭名昭著的例子:

    a[i] = b[i++];

    在上面的例子中,我们只知道b的下标值没有被增加。a的下标i值可能是自增后的值也可能是自增前的值。

    struct bar_t { struct bar_t *next; } bar;
    bar->next = bar = tmp;

在第二个例子中,bar->next的地址很可能在bar被赋值之前被计算使用。

bar = bar->next = tmp;

第三个例子中,bar可能在bar->next之前被赋值。虽然这可能有悖于"赋值从右到左处理"的规则,但这确是一个合法的解析。考虑下 面的例子:

long i;
short a[N];
i = old
i = a[i] = new;

赋给i的值必须是一个按照从右到左的处理顺序进行赋值处理后的值。但是i可能在ai被赋值前而被赋值为"(long) (short)new"。不同编译器作法不同。

    * 质疑代码中出现的数值(“魔数”)。

    * 避免使用预处理器技巧。一些诸如使用/ /粘和字符串以及依赖参数字符串展开的宏会破坏代码可靠性。

    #define FOO(string)    (printf("string = %s",(string)))
    …
  FOO(filename);

只是在有些时候会扩展为

 (printf("filename = %s",(filename)))

小心。诡异的预处理器在一些机器上可能导致宏异常中断。下面是一个宏的两种不同实现版本:

  #define LOOKUP(chr)    (a['c'+(chr)])    /* Works as intended. */
  #define LOOKUP(c)    (a['c'+(c)])        /* Sometimes breaks. */

第二个版本的LOOKUP可能以两种不同的方式扩展,并且会导致代码异常中断。

    * 熟悉现有的库函数和定义(但不用太熟悉。与其外部接口相反,库基础设施的内部细节常会改变并且没有警告,这些细节常常也是不可移植的)。你不应该再自己重 新编写字符串比较例程、终端控制例程或为系统结构编写你自己的定义。自己动手实现既浪费你的时间,又使得你的代码可读性变差,因为另外一个读者需 要知道你是否在新的实现中做了什么特殊的事情,并尝试证实它们的存在。同时这样做会使得你无法充分利用一些辅助的微代码或其他有助于提高系统例程 性能的方法。更进一步,它将是一个bug的高产源头。如果可能的话,要知道公共库之间的差异(如ANSI、POSIX等等)。

    * 如果lint可用,请使用lint。这个工具对于查找代码中机器相关的构造、其他不一致性以及顺利通过编译器检查的程序bug时具有很高价值。如果你的编 译器具备打开警告的开关,请打开它。

    * 质疑在代码块内部的与代码块外部switch或goto有关联的标签(Label)。

    无论类型在哪里,参数都应该被转换为适当的类型。当NULL用在没有原型的函数调用时,请对NULL进行转换。不要让函数调用成为类型欺骗发生的地方。C 语言的类型提升规则很是让人费解,所以尽量小心。例如,如果一个函数接受一个32位长的长整型做为参数,但实际传入的却是一个16位长的整型数, 函数栈可能会无法对齐,这个值也可能会被错误提升。

    * 在混用有符号和无符号值的算术计算时请使用显式类型转换

    * 应该谨慎使用跨程序的goto、longjmp。很多实现"忘记"恢复寄存器中的值了。尽可能将关键的值声明为volatile,或将它们注释为 VOLATILE。

    * 一些链接器将名字转换为小写,并且一些链接器只识别前六个字母作为唯一标识。在这些系统上程序可能会悄悄地中断运行。

    * 当心编译器扩展。如果使用了编译器扩展,请将他们视为机器依赖并用文档记录下来。

    * 通常程序无法在数据段执行代码或者无法将数据写入代码段。即使程序可以这么做,也无法保证这么做是可靠的。

17. 标准C

现代C编译器支持一些或全部的ANSI提议的标准C。无论何时可能的话,尽量用标准C编写和运行程序,并且使用诸如函数原型,常量存储以及 volatile(易失性)存储等特性。标准C通过给优化器提供有有效的信息以提升程序的性能。标准C通过保证所有编译器接受同样的输入语言以及提供相关 机制隐藏机器相关内容或对于那些机器相关代码提供警告的方式提升代码的可移植性。

17.1 兼容性

编写很容易移植到老编译器上的代码。例如,有条件地在global.h中定义一些新(标准中的)关键字,比如const和volatile。标准编译器预 定义了预处理器符号STDC(见脚注8)。void类型很难简单地处理正确,因为很多老编译器只理解void,但不认识void。最简单的方法就是定义一 个新类型VOIDP(与机器和编译器相关),通常在老编译器下该类型被定义为char*。

#if __STDC__
    typedef void *voidp;
#   define COMPILER_SELECTED
#endif
#ifdef A_TARGET
#    define const
#    define volatile
#    define void int
    typedef char *voidp;
#    define COMPILER_SELECTED
#endif
#ifdef …
    …
#endif
#ifdef COMPILER_SELECTED
#    undef COMPILER_SELECTED
#else
    { NO TARGET SELECTED! }
#endif

注意在ANSI C中,#必须是同一行中预处理器指示符的第一个非空白字符。在一些老编译器中,它必须是同一行中的第一个字符。

当一个静态函数具有前置声明时,前置声明必须包含存储修饰符。在一些老编译器中,这个修饰符必须是"extern"。对于ANSI编译器,这个存储修饰符 必须为static,但全局函数依然必须声明为extern。因此,静态函数的前置声明应该使用一个#define,例如FWD_STATIC,并通 过#ifdef适当定义。

一个"#ifdef NAME"应该要么以"#endif"结尾,要么以"#endif / NAME /结尾,不应该用"#endif NAME"结尾。对于短小的#ifdef不应该使用注释,因为通过代码我们可以明确其含义。

ANSI的三字符组可能导致内容包含??的字符串的程序神秘的中断。

17.2 格式化

ANSI C的代码风格与常规C一样,但有两点意外:存储修饰符(storage qualifiers)和参数列表。

由于const和volatile的绑定规则很奇怪,因此每个const或volatile对象都应该单独声明。

int const *s;        /* YES */
int const *s, *t;    /* NO */

具备原型的函数将参数声明和定义归并在一个参数列表中了。应该在函数的注释中提供各个参数的注释。

/*
 * `bp': boat trying to get in.
 * `stall': a list of stalls, never NULL.
 * returns stall number, 0 => no room.
 */
int
enter_pier (boat_t const *bp, stall_t *stall)
{
    …

17.3 原型

应该使用函数原型使得代码更加健壮并且运行时性能更好。不幸地是原型的声明

extern void bork (char c);

与定义不兼容。

void
bork (c)
char c;
 …

原型中c应该以机器上最自然的类型传入,很可能是一个字节。而非原型化(向后兼容)的定义暗示c总是以一个整型传入。如果一个函数具有可类型提升的参数, 那么调用者和被调用者必须以相等地方式编译。要么都必须使用函数原型,要么都不使用原型。如果在程序设计时参数就是可以提升类型的,那么问题就可以被避 免,例如bork可以定义成接受一个整型参数。

如果定义也是原型化的,上面的声明将工作正常。

void
bork (char c)
{
    …

不幸地是,原型化的语法将导致非ANSI编译器拒绝这个程序。

但我们可以很容易地通过编写外部声明来同时适应原型与老编译器。

#if __STDC__
#    define PROTO(x) x
#else
#    define PROTO(x) ()
#endif

extern char **ncopies PROTO((char *s, short times));

注意PROTO必须使用双层括号。

最后,最好只使用一种风格编写代码(例如,使用原型)。当需要非原型化的版本时,可使用一个自动转换工具生成。

17.4 Pragmas

Pragmas用于以一种可控的方式引入机器相关的代码。很显然,pragma应该被视为机器相关的。不幸地是,ANSI pragmas的语法使得我们无法将其隔离到机器相关的头文件中了。

Pragmas分为两类。优化相关的可以被安全地忽略。而那些影响系统行为(需要pragmas)的Pragmas则不能忽略。需要的pragmas应该结合#ifdef使用,这样如果一个pragma都没有选到,编译过程将退出。

两个编译器可能通过两个不同的方式使用同一个给定的pragma。例如,一个编译器可能使用haggis发出一个优化信号。而另一个可能使用它暗示一个特 定语句,一旦执行到此,程序应该退出。不过,一旦使用了pragma,它们必须总是被机器相关的#ifdef包围。对于非ANSI编译器,Pragmas 必须总是被#ifdef。确保对#pragma的#进行缩进,否则一些较老的预处理器处理它时会挂起。

#if defined(__STDC__) && defined(USE_HAGGIS_PRAGMA)
    #pragma (HAGGIS)
#endif

    "ANSI标准中描述的'#pragma'命令具有任意实现定义的影响。在GNU C预处理中,'#pragma'首先尝试运行游戏'rogue';如果失败,它将尝试运行游戏'hack';如果失败,它将尝试运行GNU Emacs显示汉诺塔;如果失败,它将报告一个致命错误。无论如何,预处理将不再继续。"

    — GNU CC 1.34 C预处理手册。

18. 特殊考虑

这节包含一些杂项:‘做'与'不做'。

    * 不要通过宏替换来改变语法。这将导致程序对于所有人都是难以理解的,除了那个肇事者。

    * 不要在需要离散值的地方使用浮点变量。使用一个浮点数作为循环计数器无疑是搬起石头砸自己的脚。总是用<=或>=测试浮点数,对它们永远不要 用精确比较(==或!=)。

    * 编译器也有bug。常见且高发的问题包括结构体赋值和位字段。你无法泛泛的预测一个编译器都有哪些bug。但你可以在程序中避免使用那些已知的在所有编译 器上都存在问题的结构。你无法让你写的任何代码都是有用的,你可能仍然会遇到bug,并且在这期间编译器很可能会被修复。因此,只有当你被强制使 用某个特定的充斥bug的编译器时,你才应该"围绕"着编译器bug写代码。

    * 不要依赖自动代码美化工具。良好代码风格的主要受益者就是代码的编写者,并且尤其在手写算法或伪代码的早期设计阶段。自动代码美化工具只应该用在那些已经 完成、语法正确并且此后不能满足当空白和缩进被更为关注的要求时。伴随着对细致程序员的细节的关注,对于那些将函数或文件布局解释清楚的工作,程 序员们会做得更好(换句话说,一些视觉布局是由意图而不是语法决定的,美化工具无法了解到程序员的思想)。粗心的程序员应该学习成为一个细致的程 序员,而不是依赖美化工具让代码可读性更好。

    * 意外地遗漏逻辑比较表达式中的第二个=是一个常犯的问题。使用显式测试。避免对赋值使用隐式测试。

abool = bbool;
if (abool) { …

当嵌入的赋值表达式使用时,确保测试是显式的,这样后续它就无法被"修复"了。

while ((abool = bbool) != FALSE) { …
while (abool = bbool) { …    /* VALUSED */
while (abool = bbool, abool) { …

    显式地注释那些在正常控制流之外被修改的变量,或其他可能在维护过程中中断的代码。

    现代编译器会自动将变量放到寄存器中。对于你认为最关键的变量慎用寄存器。在极端情况下,用寄存器标记2-4个最为关键的值,并且将剩余的标记为 REGISTER。后者在那些具有较多寄存器的机器上可以#define为寄存器。

19. Lint

Lint是一个C程序检查工具,用于检查C语言源码文件,探测和报告诸如类型不兼容、函数定义与调用不一致以及潜在的bug等情况。强烈建议在所 有程序上使用lint工具,并且期望大多数工程将lint作为官方验收程序的一部分。

应该注意的是使用lint的最好方法不是将lint作为官方验收之前的一道必须跨过的栅栏,而是作为一个在代码发生添加或变更之后使用的工具。 Lint可以发现一些隐藏的bug并且可以在问题发生前保证程序的可移植性。lint产生的许多信息确实暗示了一些事情是错误的。一个有意思的故 事是关于一个漏掉了fprintf的一个参数的程序:

fprintf ("Usage: foo -bar <file>\n");

作者从未有过一个问题。但每当一个正常用户在命令行上犯错,这个程序就会产生一个core。许多版本的lint工具都能发现这个问题。

大多lint选项都值得我们学习。一些选项可能在合法的代码上给出警告,但它们也会捕捉到许多把事情搞遭的代码。注意'–p'只能为库的一个子 集检查函数调用和类型的一致性,因此程序为了最大化的覆盖检查,应该同时进行带–p和不带–p的lint检查。

Lint也可以识别代码里的一些特殊注释。这些注释可以强制让lint在发现问题时关闭警告输出,还可以作为一些特殊代码的文档。

20. Make

另外一个非常有用的工具是make。在开发过程中,make只会重新编译那些上次make后发生了改变的模块。它也可以用于自动化其他任务。一些 常见的约定包括:

all
执行所有二进制文件的构建过程

clean
删除所有中间文件

debug
构建一个测试用二进制文件a.out或debug

depend
制作可传递的依赖关系

install
安装二进制文件,库等

deinstall
取消安装

mkcat
安装手册

lint
运行lint工具

print/list
制作一个所有源文件的拷贝

shar
为所有源文件制作一个shar文件

spotless
执行make clean,并将源码存入版本控制工具。注意:不会删除Makefile,即便它是一个源文件。

source
撤销spotless所做的事情。

tags
运行ctags(建议使用-t标志)

rdist
分发源码到其他主机

file.c
从版本控制系统中检出这个文件

除此之外,通过命令行也可以定义Makefile使用的值(如"CFLAGS")或源码中使用的值(如"DEBUG")。

21. 工程相关的标准

除了这里提到内容外,每个独立的工程都期望能建立附加标准。下面是每个工程程序管理组需要考虑的问题中的一部分:

    * 哪些额外的命名约定需要遵守?尤其是,那些用于全局数据的功能归类以及结构体或联合体成员名字的系统化的前缀约定非常有用。

    * 什么样的头文件组织适合于工程特定的数据体系结构?

    * 应该建立什么样的规程来审核lint警告?需要确立一个与lint选项一致的宽容度,保证lint不会针对一些不重要的问题给出警告,但同时保证真正的bug或不一致问题不被隐藏。

    * 如果一个工程建立了自己的档案库,它应该计划向系统管理员提供一个lint库文件。这个lint库文件允许lint工具检查对库函数的兼容性使用。

    * 需要使用哪种版本控制工具?

22. 结论

这里描述了一套C语言编程风格的标准。其中最重要的几点是:

    * 合理使用空白和注释,使得我们通过代码布局就可以清楚地看出程序的结构。使用简单表达式、语句和函数,使他们可以很容易地被理解。

    * 记住,在将来某个时候你或其他人很可能会被要求修改代码或让代码运行在一台不同的机器上。精心编写代码,使得其可以移植到尚不确定的机器上。局部化你的优化,因为这些优化经常让人困惑,并且对于该优化措施是否适合其他机器我们持悲观态度。

    * 许多风格选择是主观武断的。保持代码风格一致比遵循这些绝对的风格规则更重要(尤其是与组织内部标准保持一致)。混用风格比任何一种糟糕的风格都更加糟糕。

无论采用哪种标准,如果认为该标准有用就必须遵循它。如果你觉得遵循某条标准时有困难,不要仅仅忽略它们,而是在和你当地的大师或组织内的有经验的程序员讨论后再做决定。

23. 参考资料

    1. B.A. Tague, C Language Portability, Sept 22, 1977. This document issued by department 8234 contains three memos by R.C. Haight, A.L. Glasser, and T.L. Lyon dealing with style and portability.
   
    2. S.C. Johnson, Lint, a C Program Checker, Unix Supplementary Documents, November 1986.
   
    3. R.W. Mitze, The 3B/PDP-11 Swabbing Problem, Memorandum for File, 1273-770907.01MF, September 14, 1977.
   
    4. R.A. Elliott and D.C. Pfeffer, 3B Processor Common Diagnostic Standards- Version 1, Memorandum for File, 5514-780330.01MF, March 30, 1978.

    5. R.W. Mitze, An Overview of C Compilation of Unix User Processes on the 3B, Memorandum for File, 5521-780329.02MF, March 29, 1978.

    6. B.W. Kernighan and D.M. Ritchie, The C Programming Language, Prentice Hall 1978, Second Ed. 1988, ISBN 0-13-110362-8.

    7. S.I. Feldman, Make — A Program for Maintaining Computer Programs, UNIXSupplementary Documents, November 1986.

    8. Ian Darwin and Geoff Collyer, Can't Happen or / NOTREACHED / or Real Programs Dump Core, USENIX Association Winter Conference, Dallas 1985
Proceedings.

    9. Brian W. Kernighan and P. J. Plauger The Elements of Programming Style. McGraw-Hill, 1974, Second Ed. 1978, ISBN 0-07-034-207-5.

    10. J. E. Lapin Portable C and UNIX System Programming, Prentice Hall 1987, ISBN 0-13-686494-5.

    11. Ian F. Darwin, Checking C Programs with lint, O'Reilly & Associates, 1989. ISBN 0-937175-30-7.

    12. Andrew R. Koenig, C Traps and Pitfalls, Addison-Wesley, 1989. ISBN 0-201-17928-8.
 

© 2013, bigwhite. 版权所有.

Related posts:

  1. C语言编码风格和标准
  2. 偿还N年前的一笔技术债
  3. 常量类型的识别-一个小例子
  4. Go与C语言的互操作
  5. 也谈C语言的Struct Hack