第八章：注释

注释是好的，不过有过度注释的危险。永远不要在注释里解释你的代码是如何运作的：更好的做法是让别人一看你的代码就可以明白，解释写的很差的代码是浪费时间。

一般的，你想要你的注释告诉别人你的代码做了什么，而不是怎么做的。也请你不要把注释放在一个函数体内部：如果函数复杂到你需要独立的注释其中的一部分，你很可能需要回到第六章看一看。你可以做一些小注释来注明或警告某些很聪明（或者槽糕）的做法，但不要加太多。你应该做的，是把注释放在函数的头部，告诉人们它做了什么，也可以加上它做这些事情的原因。

当注释内核API函数时，请使用kernel-doc格式。请看

Documentation/kernel-doc-nano-HOWTO.txt和scripts/kernel-doc以获得详细信息。

Linux的注释风格是C89“/* ... */”风格。不要使用C99风格“// ...”注释。

长（多行）的首选注释风格是：

        /*

         * This is the preferred style for multi-line

         * comments in the Linux kernel source code.

         * Please use it consistently.

         *

         * Description:  A column of asterisks on the left side,

         * with beginning and ending almost-blank lines.

         */

注释数据也是很重要的，不管是基本类型还是衍生类型。为了方便实现这一点，每一行应只声明一个数据（不要使用逗号来一次声明多个数据）。这样你就有空间来为每个数据写一段小注释来解释它们的用途了。

                第九章：你已经把事情弄糟了

这没什么，我们都是这样。可能你的使用了很长时间Unix的朋友已经告诉你“GNU emacs”能自动帮你格式化C源代码，而且你也注意到了，确实是这样，不过它所使用的默认值和我们想要的相去甚远（实际上，甚至比随机打的还要差——无数个猴子在GNU emacs里打字永远不会创造出一个好程序）（译注：请参考Infinite Monkey Theorem）

所以你要么放弃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 tab-width 8)

  (setq indent-tabs-mode t)

  (setq c-basic-offset 8))

这样就定义了M-x linux-c-mode命令。当你hack一个模块的时候，如果你把字符串

-*- linux-c -*-放在头两行的某个位置，这个模式将会被自动调用。如果你希望在你修改

/usr/src/linux里的文件时魔术般自动打开linux-c-mode的话，你也可能需要添加

(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个字符缩进”），或者使用“scripts/Lindent”，这样就可以以最时髦的方式缩进源代码。“indent”有很多选项，特别是重新格式化注释的时候，你可能需要看一下它的手册页。不过记住：“indent”不能修正坏的编程习惯。