C程序代码风格

    下面这篇文章是linux内核中Documentation/CodingStyle文件，觉得挺有意思，就顺手把它译出来了，因为虽然这只是“linux”的代码风格，但优秀的C程序风格大致无二。特别是emacs相关的东西，肯定有误译，请多指正。

    Linux内核编码风格

    这篇简短的文章描述了Linux内核首选的编码风格。编码风格是很个人化的东西，我不会把自己的观点强加给任何人。但是，Linux内核的代码毕竟是我必须有能力维护的，因此我宁愿它的编码风格是我喜欢的。请至少考虑一下这一点。
   
    首先，我建议打印一份《GNU编码标准》，不要阅读它。烧掉它，它不过是象征性的姿态。
   
    然后，请看： 

    第 1 章： 缩进

    Tabs(制表符)是8个字符的大小，因此缩进也应该是8个字符的大小。有些叛逆主张试图把缩进变成4个(甚至是2个！)字符的长度，这就好象试图把PI(案，圆周率)定义成3是一样的。
   
    依据：缩进背后的思想是:清楚地定义一个控制块从哪里开始，到哪里结束。尤其是在你连续不断的盯了20个小时的屏幕后，如果你有大尺寸的缩进。你将更容易发现缩进的好处。
   
    现在，有些人说8个字符大小的缩进导致代码太偏右了，并且在一个80字符宽的终端屏幕上看着很不舒服。对这个问题的回答是：如果你有超过3个级别的缩进，你就有点犯糊涂了，应当修改你的程序。
   
    简而言之，8个字符的缩进使程序更易读，而且当你把功能隐藏的太深时，多层次的缩进还会对此很直观的给出警告。要留心这种警告信息。 
    
    第 2 章： 放置花括号

    C程序中另一个要主意的就是花括号的放置。与缩进尺寸不同的是，关于如何放置花括号没有技术上的理由。但是，首选的方法是象先知Brain Kernighan和Dennis Ritchie展现的那样：把左括号放在行尾，右括号放在行首。也就是：
   
   if (x is true) {
      we do y
   }
   
    然而，还有另外一种情况，就是函数：函数应当把左右括号都放在行首。也就是：
   
   int function(int x)
   {
      body of function
   }
   
    叛逆的人们所在皆有。他们说，这样会导致…嗯，不一致性(案，指函数的花括号使用与其他情况不统一)。但是所有正确思考的人都知道：(1) K&R是正确的；(2) K&R还是正确的。 而且，函数与别任何东西都不一样(在C语言中你没法隐藏它)。
   
    注意，右括号所在的行不应当有其它东西，除非跟随着一个条件判断。也就是do-while语句中的“while”和if-else语句中的“else”。象这样：
   
   do {
      body of do-loop
   } while (condition);
   
和：
   
   if (x == y) {
      ..
   } else if (x > y) {
      ...
   } else {
      ....
   }
   
    依据： K&R。
   
    而且，注意这种花括号的放置减少了空行的数目，并没损害可读性。因此，当屏幕上不可以有很多空行时(试想25行的终端屏幕)，你就有更多的空行来安插注释。 
    
    第 3 章： 命名

    C是一门朴素的语言，你使用的命名也应该这样。与Modula-2和Pascal程序员不同，C程序员不使用诸如“ThisVariableIsATemporaryCounter”这样“聪明”的名字。C程序员应该叫它“tmp”，这写起来更简单，也不会更难懂。 
 
    然而，当面对复杂情况时就有些棘手，给全局变量取一个描述性的名字是必要的。把一个全局函数叫做“foo”是一种目光短浅的行为。
   
    全局变量(只当你确实需要时才用)应该有描述性的名字，全局函数也一样。如果你有一个统计当前用户个数的函数，应当把它命名为“count_active_user()”或者简单点些的类似名称，不应该命名为“cntusr()”。
   
    把函数类型写进函数名(即所谓的“匈牙利命名法”)简直就是大脑有问题──编译器总是知道函数的类型并且能加以检查，这种命名法只会弄糊涂程序员自己。怪不得微软总是制造充满bug的程序。
   
    局部变量的名字应该尽量短，而且说到点子上。如果你有个普通的整型循环计数变量，应当命名为“i”。命名为“loop_counter”并不能带来任何成效，如果它不被误解的话(案，这里的言外之意是说，如果被误解就更惨了)。与此类似，“tmp”可以作为一个用来存储任何类型临时值的变量的名字。
   
    如果你害怕弄混淆局部变量(s)的名字，你就面临着另一个问题，也叫作“函数增长荷尔蒙失调综合症”。请参考下一章。 
    
    第 4 章： 函数

    函数应当短而精美，而且只做一件事。它们应当占满1或2个屏幕(就象我们知道的那样，ISO/ANSI的屏幕大小是80X24)，只做一件事并且把它做好。
 
    一个函数的最大长度与它的复杂度和缩进级别成反比。所以，如果如果你有一个概念上简单(案，“简单”是simple而不是easy)的函数，它恰恰包含着一个很长的case语句，这样你不得不为不同的情况准备不懂的处理，那么这样的长函数是没问题的。
   
    然而，如果你有一个复杂的函数，你猜想一个并非天才的高一学生可能看不懂得这个函数，你就应当努力把它减缩得更接近前面提到的最大函数长度限制。可以使用一些辅助函数，给它们取描述性的名字(如果你认为这些辅助函数的调用是性能关键的，可以让编译器把它们内联进来，这比在单个函数内完成所有的事情通常要好些)。
   
    对函数还存在另一个测量标准：局部变量的数目。这不该超过5到10个，否则你可能会弄错。应当重新考虑这个函数，把它分解成小片。人类的大脑一般能同时记住7个不同的东西，超过这个数目就会犯糊涂。或许你认为自己很聪明，那么请你理解一下从现在开始的2周时间你都做什么了。 

    第 5 章：注释

    注释是有用的，但过量的注释则是有害的。不要试图在注释中解释你的代码是如何工作的：把代码是如何工作的视为一件显然的事情会更好些，而且，给糟糕的代码作注释则是在浪费时间。

    通常，你愿意自己的注释说出代码是做什么的，而不是如何做。还有，尽量避免在函数体内作注释：如果函数很复杂，你很可能需要分开来注释，回头到第4章去看看吧。你可以给一段代码──漂亮的或丑陋的──作注释以引起注意或警告，但是不要过量。取而代之，应当把注释放在函数首部，告诉人们该函数作什么，而不是为什么这样做。 

    第 6 章：你把事情弄乱了

    好吧，我们来看看。很可能有长期使用UNIX的人告诉过你，“GNU emacs”能自动为你格式化C程序源代码，你注意到这是真的，它确实能做到，但是缺省情况下它的用处远远小于期望值──键入无数的monkeys到GNU emacs中绝不可能造出好的程序。
 
    因此，你可以或者删除GNU emacs，或者对它进行理智的配置。对于后者，可以把下面的行粘贴到你的.emacs文件中：
   
   (defun linux-c-mode ()
   "C mode with adjusted defaults for use with the Linux kernel."
   (interactive)
   (c-mode)
   (c-set-style "K&R")
   (setq c-basic-offset 8))
   
    这将会定义一个把C代码弄成linux风格的命令。当hacking一个模块时，如果你把“-*- linux-c -*-”放到了最初的两行，这个模块将被自动调用。而且，如果你打算每当在/usr/src/linux下编辑源文件时就自动调用它，也许你会把下面的命令：
   (setq auto-mode-alist (cons '("/usr/src/linux.*/.*\\.[ch]$" . linux-c-mode)
            auto-mode-alist))
    添加进你的.emacs文件。
   
    但是，即使你没能让emacs正确做到格式化，也并非将就此一无所有：还有“indent”程序呢。
   
    嗯，再提醒一下，GNU indent跟GNU emacs有同样的毛病，这就需要你给它一些命令行选项。然而，这不是很糟糕的事，因为即使是GNU indent也承认K&R的权威性(GNU的人不是魔鬼，他们只是在这里太过严格了，以致于误导人)，所以你可以只需给indent这样的选项：“-kr -i8”(表示“K&R风格，8个字符的缩进”)。
   
    “indent”程序有很多选项，特别是当为重排过的程序作注释的时候，你需要看一下它的手册。记住：“indent”可不是修正糟糕程序的万能钥匙。 
    
    第 7 章： 配置文件(configuration-files)

    对配置选项来说(arch/xxx/config.in和所有的Config.in文件)，使用不同的缩进风格。
 
    若代码中的缩进级别为3，配置选项就应该为2,这样可以暗示出依赖关系。后者只是用于bool/tristate(即二态/三态)的选项。对其它情况用常识就行了。举例来说：

   if [ "$CONFIG_EXPERIMENTAL" = "y" ]; then
      tristate 'Apply nitroglycerine inside the keyboard (DANGEROUS)' CONFIG_BOOM
      if [ "$CONFIG_BOOM" != "n" ]; then
         bool '  Output nice messages when you explode' CONFIG_CHEER
      fi
   fi

    通常CONFIG_EXPERIMENTAL应当在所有不稳定的选项的周围出现。所有已知会破坏数据的选项(如文件系统的实验性的写支持功能)应当被标记为(DANGEROUS)，其他实验性的选项应当被标记为(EXPERIMENTAL)。 
    

    第 8 章： 数据结构

    假如数据结构在其被创建/销毁的线程环境(案：这里说的线程是一个执行实体，可能是进程、内核线程或其它)之外还具有可见性，那么他们都该有引用计数。 在内核中没有垃圾收集机制(而且内核之外的垃圾收集也是缓慢而低效的)，这意味着你绝对应该为每一次使用进行引用计数。
   
    引用计数意味着你可以避开锁，还能允许多个线程并行访问该数据结构──而且不用担心仅仅因为访问数据结构的线程睡眠了一会儿或者干别的去了，它们就会消失。
   
    注意，锁不是引用计数的替代品。锁是用来保持数据结构的一致性的，而引用计数是一种内存管理技术。通常二者都需要，而且不会彼此混淆。 下面这篇文章是linux内核中Documentation/CodingStyle文件，觉得挺有意思，就顺手把它译出来了，因为虽然这只是“linux”的代码风格，但优秀的C程序风格大致无二。特别是emacs相关的东西，肯定有误译，请多指正。