Documentation / zh_CN / CodingStyle

Based on kernel version 2.6.26. Page generated on 2008-07-16 21:13 EST.

	Chinese translated version of Documentation/CodingStyle
	
	If you have any comment or update to the content, please post to LKML directly.
	However, if you have problem communicating in English you can also ask the
	Chinese maintainer for help.  Contact the Chinese maintainer, if this
	translation is outdated or there is problem with translation.
	
	Chinese maintainer: Zhang Le <r0bertz[AT]gentoo[DOT]org>
	---------------------------------------------------------------------
	Documentation/CodingStyle的中文翻译
	
	如果想评论或更新本文的内容，请直接�信到LKML。如果你使用英文交�有困难的�，也�
	以�中文版维护者求助。如果本翻译更新��时或者翻译存在问题，请�系中文版维护者。
	
	中文版维护者： 张� Zhang Le <r0bertz[AT]gentoo[DOT]org>
	中文版翻译者： 张� Zhang Le <r0bertz[AT]gentoo[DOT]org>
	中文版校译者： 王� Wang Cong <xiyou.wangcong[AT]gmail[DOT]com>
	               wheelz <kernel.zeng[AT]gmail[DOT]com>
	               管旭东 Xudong Guan <xudong.guan[AT]gmail[DOT]com>
	               Li Zefan <lizf[AT]cn.fujitsu[DOT]com>
	               Wang Chen <wangchen[AT]cn.fujitsu[DOT]com>
	以下为正文
	---------------------------------------------------------------------
	
			Linux内核代�风格
	
	这是一个简短的文档，�述了linux内核的首选代�风格。代�风格是因人而异的，而且我
	�愿�把我的观点强加给任何人，�过这里所讲述的是我必须�维护的代�所�守的风格，
	并且我也希望�大多数其他代�也能�守这个风格。请在写代�时至少考虑一下本文所述的
	风格。
	
	首先，我建议你打�一份GNU代�规范，然���读它。烧了它，这是一个具有�大象�性
	�义的动作。
	
	�管怎样，现在我们开始：
	
	
		 	第一章：缩进
	
	制表符是8个字符，所以缩进也是8个字符。有些异端�动试图将缩进�为4（乃至2）个字符
	深，这几乎相当于�试将圆周率的值定义为3。
	
	�由：缩进的全部�义就在于清楚的定义一个控制�起止于何处。尤其是当你盯�你的�幕
	连续看了20�时之�，你将会�现大一点的缩进会使你更容易分辨缩进。
	
	现在，有些人会抱怨8个字符的缩进会使代���边移动的太远，在80个字符的终端�幕上
	就很难读这样的代�。这个问题的答案是，如果你需�3级以上的缩进，�管用何�方�你
	的代�已�有问题了，应该修正你的程�。
	
	简而言之，8个字符的缩进�以让代�更容易阅读，还有一个好处是当你的函数嵌套太深的
	时候�以给你警告。留心这个警告。
	
	在switch语�中消除多级缩进的首选的方�是让“switch�和从属于它的“case�标签对�于�
	一列，而��“两次缩进�“case�标签。比如：
	
		switch (suffix) {
		case 'G':
		case 'g':
			mem <<= 30;
			break;
		case 'M':
		case 'm':
			mem <<= 20;
			break;
		case 'K':
		case 'k':
			mem <<= 10;
			/* fall through */
		default:
			break;
		}
	
	
	��把多个语�放在一行里，除�你有什么东西���：
	
		if (condition) do_this;
		  do_something_everytime;
	
	也��在一行里放多个赋值语�。内核代�风格超级简�。就是���能导致别人误读的表
	达�。
	
	除了注释�文档和Kconfig之外，��使用空格�缩进，��的例�是例外，是有�为之。
	
	选用一个好的编辑器，��在行尾留空格。
	
	
			第二章：把长的行和字符串打散
	
	代�风格的�义就在于使用平常使用的工具�维�代�的�读性和�维护性。
	
	�一行的长度的�制是80列，我们强烈建议您�守这个惯例。
	
	长于80列的语��打散�有�义的片段。�个片段�明显短于原�的语�，而且放置的�置
	也明显的��。�样的规则也适用于有很长�数列表的函数头。长字符串也�打散�较短的
	字符串。唯一的例外是超过80列�以大幅度�高�读性并且�会��信�的情况。
	
	void fun(int a, int b, int c)
	{
		if (condition)
			printk(KERN_WARNING "Warning this is a long printk with "
							"3 parameters a: %u b: %u "
							"c: %u \n", a, b, c);
		else
			next_statement;
	}
	
			第三章：大括�和空格的放置
	
	C语言风格中�外一个常�问题是大括�的放置。和缩进大���，选择或弃用��放置策
	略并没有多少技术上的原因，�过首选的方�，就�Kernighan和Ritchie展示给我们的，是
	把起始大括�放在行尾，而把结�大括�放在行首，所以：
	
		if (x is true) {
			we do y
		}
	
	这适用于所有的�函数语��（if�switch�for�while�do）。比如：
	
		switch (action) {
		case KOBJ_ADD:
			return "add";
		case KOBJ_REMOVE:
			return "remove";
		case KOBJ_CHANGE:
			return "change";
		default:
			return NULL;
		}
	
	�过，有一个例外，那就是函数：函数的起始大括�放置于下一行的开头，所以：
	
		int function(int x)
		{
			body of function
		}
	
	全世界的异端�能会抱怨这个�一致性是……呃……�一致的，�过所有�维�全的人都知�（
	a）K&R是_正确的_，并且（b）K&R是正确的。此外，�管怎样函数都是特殊的（在C语言中
	，函数是�能嵌套的）。
	
	注�结�大括�独自��一行，除�它��跟��一个语�的剩余部分，也就是do语�中的
	“while�或者if语�中的“else�，�这样：
	
		do {
			body of do-loop
		} while (condition);
	
	和
	
		if (x == y) {
			..
		} else if (x > y) {
			...
		} else {
			....
		}
	
	�由：K&R。
	
	也请注�这�大括�的放置方�也能使空（或者差�多空的）行的数�最�化，�时�失�
	读性。因此，由于你的�幕上的新行是���生资�（想想25行的终端�幕），你将会有更
	多的空行�放置注释。
	
	当�有一个�独的语�的时候，�用加�必�的大括�。
	
	if (condition)
		action();
	
	这点�适用于本身为�个�件语�的一个分支的�独语�。这时需�在两个分支里都使用大
	括�。
	
	if (condition) {
		do_this();
		do_that();
	} else {
		otherwise();
	}
	
			3.1：空格
	
	Linux内核的空格使用方�（主�）�决于它是用于函数还是关键字。（大多数）关键字�
	�加一个空格。值得注�的例外是sizeof�typeof�alignof和__attribute__，这些关键字
	�些程度上看起�更�函数（它们在Linux里也常常伴��括�而使用，尽管在C语言里这样
	的�括��是必需的，就�“struct fileinfo info�声明过�的“sizeof info�）。
	
	所以在这些关键字之�放一个空格：
		if, switch, case, for, do, while
	但是��在sizeof�typeof�alignof或者__attribute__这些关键字之�放空格。例如，
		s = sizeof(struct file);
	
	��在�括�里的表达�两侧加空格。这是一个�例：
	
		s = sizeof( struct file );
	
	当声明指针类型或者返回指针类型的函数时，“*�的首选使用方�是使之�近���或者函
	数�，而�是�近类型�。例�：
	
		char *linux_banner;
		unsigned long long memparse(char *ptr, char **retptr);
		char *match_strdup(substring_t *s);
	
	在大多数二元和三元�作符两侧使用一个空格，例如下�所有这些�作符：
	
		=  +  -  <  >  *  /  %  |  &  ^  <=  >=  ==  !=  ?  :
	
	但是一元�作符���加空格：
		&  *  +  -  ~  !  sizeof  typeof  alignof  __attribute__  defined
	
	�缀自加和自�一元�作符��加空格：
		++  --
	
	�缀自加和自�一元�作符��加空格：
		++  --
	
	“.�和“->�结构体�员�作符���加空格。
	
	��在行尾留空白。有些�以自动缩进的编辑器会在新行的行首加入适�的空白，然�你
	就�以直接在那一行输入代�。�过�如你最�没有在那一行输入代�，有些编辑器就�
	会移除已�加入的空白，就�你故�留下一个�有空白的行。包�行尾空白的行就这样产
	生了。
	
	当git�现补�包�了行尾空白的时候会警告你，并且�以应你的�求去掉行尾空白；�过
	如果你是正在打一系列补�，这样�会导致��的补�失败，因为你改�了补�的上下文。
	
	
			第四章：命�
	
	C是一个简朴的语言，你的命�也应该这样。和Modula-2和Pascal程�员��，C程�员�使
	用类似ThisVariableIsATemporaryCounter这样�丽的�字。C程�员会称那个��为“tmp�
	，这样写起�会更容易，而且至少�会令其难于�解。
	
	�过，虽然混用大�写的�字是��倡使用的，但是全局��还是需�一个具�述性的�字
	。称一个全局函数为“foo�是一个难以饶�的错误。
	
	全局��（�有当你真正需�它们的时候�用它）需�有一个具�述性的�字，就�全局函
	数。如果你有一个�以计算活动用户数�的函数，你应该�它“count_active_users()�或者
	类似的�字，你�应该�它“cntuser()�。
	
	在函数�中包�函数类型（所谓的匈牙利命�法）是脑�出了问题——编译器知�那些类型而
	且能够检查那些类型，这样��能把程�员弄糊涂了。难怪微软总是制造出有问题的程�。
	
	本地���应该简短，而且能够表达相关的�义。如果你有一些�机的整数型的循环计数器
	，它应该被称为“i�。�它“loop_counter�并无益处，如果它没有被误解的�能的�。类似
	的，“tmp��以用�称呼任�类型的临时��。
	
	如果你怕混淆了你的本地���，你就�到�一个问题了，��函数增长�尔蒙失衡综�症
	。请看第六章（函数）。
	
	
			第五章：Typedef
	
	��使用类似“vps_t�之类的东西。
	
	对结构体和指针使用typedef是一个错误。当你在代�里看到：
	
		vps_t a;
	
	这代表什么��呢？
	
	相�，如果是这样
	
		struct virtual_container *a;
	
	你就知�“a�是什么了。
	
	很多人认为typedef“能�高�读性�。实际�是这样的。它们�在下列情况下有用：
	
	 (a) 完全��明的对象（这�情况下�主动使用typedef���这个对象实际上是什么）。
	
	     例如：“pte_t�等��明对象，你�能用�适的访问函数�访问它们。
	
	     注����明性和“访问函数�本身是�好的。我们使用pte_t等类型的原因在于真的是
	     完全没有任何共用的�访问信�。
	
	 (b) 清楚的整数类型，如此，这层抽象就�以帮助消除到底是“int�还是“long�的混淆。
	
	     u8/u16/u32是完全没有问题的typedef，�过它们更符�类别(d)而�是这里。
	
	     �次注���这样�，必须事出有因。如果�个��是“unsigned long“，那么没有必�
	
		typedef unsigned long myflags_t;
	
	     �过如果有一个明确的原因，比如它在��情况下�能会是一个“unsigned int�而在
	     其他情况下�能为“unsigned long�，那么就��犹豫，请务必使用typedef。
	
	 (c) 当你使用sparse按字�的创建一个新类型��类型检查的时候。
	
	 (d) 和标准C99类型相�的类型，在�些例外的情况下。
	
	     虽然让眼�和脑筋�适应新的标准类型比如“uint32_t��需�花很多时间，�是有些
	     人�然拒�使用它们。
	
	     因此，Linux特有的等�于标准类型的“u8/u16/u32/u64�类型和它们的有符�类型是被
	     �许的——尽管在你自己的新代�中，它们�是强制�求�使用的。
	
	     当编辑已�使用了�个类型集的已有代�时，你应该�循那些代�中已��出的选择。
	
	 (e) �以在用户空间安全使用的类型。
	
	     在�些用户空间��的结构体里，我们�能�求C99类型而且�能用上��到的“u32�
	     类型。因此，我们在与用户空间共享的所有结构体中使用__u32和类似的类型。
	
	�能还有其他的情况，�过基本的规则是永远��使用typedef，除�你�以明确的应用上
	述�个规则中的一个。
	
	总的�说，如果一个指针或者一个结构体里的元素�以��的被直接访问到，那么它们就�
	应该是一个typedef。
	
	
			第六章：函数
	
	函数应该简短而漂亮，并且�完�一件事情。函数应该�以一�或者两�显示完（我们都知
	�ISO/ANSI�幕大�是80x24），��一件事情，而且把它�好。
	
	一个函数的最大长度是和该函数的��度和缩进级数��比的。所以，如果你有一个�论上
	很简�的�有一个很长（但是简�）的case语�的函数，而且你需�在�个case里�很多很
	�的事情，这样的函数尽管很长，但也是�以的。
	
	�过，如果你有一个��的函数，而且你怀疑一个天分�是很高的高中一年级学生�能甚至
	��清楚这个函数的目的，你应该严格的�守���到的长度�制。使用辅助函数，并为之
	�个具�述性的�字（如果你觉得它们的性能很��的�，�以让编译器内�它们，这样的
	效果往往会比你写一个��函数的效果�好。）
	
	函数的�外一个衡�标准是本地��的数�。此数��应超过5�10个，�则你的函数就有
	问题了。�新考虑一下你的函数，把它分拆�更�的函数。人的大脑一般�以轻�的�时跟
	踪7个��的事物，如果�增多的�，就会糊涂了。�便你�颖过人，你也�能会记�清你2
	个星期��过的事情。
	
	在�文件里，使用空行隔开��的函数。如果该函数需�被导出，它的EXPORT*�应该紧贴
	在它的结�大括�之下。比如：
	
	int system_is_up(void)
	{
		return system_state == SYSTEM_RUNNING;
	}
	EXPORT_SYMBOL(system_is_up);
	
	在函数原型中，包�函数�和它们的数�类型。虽然C语言里没有这样的�求，在Linux里这
	是�倡的�法，因为这样�以很简�的给读者�供更多的有价值的信�。
	
	
			第七章：集中的函数退出途径
	
	虽然被�些人声称已�过时，但是goto语�的等价物还是�常被编译器所使用，具体形�是
	无�件跳转指令。
	
	当一个函数从多个�置退出并且需��一些通用的清�工作的时候，goto的好处就显现出�
	了。
	
	�由是：
	
	- 无�件语�容易�解和跟踪
	- 嵌套程度��
	- �以��由于修改时忘记更新�个�独的退出点而导致的错误
	- �轻了编译器的工作，无需删除冗余代�;)
	
	int fun(int a)
	{
		int result = 0;
		char *buffer = kmalloc(SIZE);
	
		if (buffer == NULL)
			return -ENOMEM;
	
		if (condition1) {
			while (loop1) {
				...
			}
			result = 1;
			goto out;
		}
		...
	out:
		kfree(buffer);
		return result;
	}
	
			第八章：注释
	
	注释是好的，�过有过度注释的�险。永远��在注释里解释你的代�是如何�作的：更好
	的�法是让别人一看你的代�就�以明白，解释写的很差的代�是浪费时间。
	
	一般的，你想�你的注释告诉别人你的代��了什么，而�是怎么�的。也请你��把注释
	放在一个函数体内部：如果函数��到你需�独立的注释其中的一部分，你很�能需�回到
	第六章看一看。你�以�一些�注释�注明或警告�些很�明（或者槽糕）的�法，但��
	加太多。你应该�的，是把注释放在函数的头部，告诉人们它�了什么，也�以加上它�这
	些事情的原因。
	
	当注释内核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��能修正�的编程习惯。
	
	
			第�章：Kconfig�置文件
	
	对于�布��树的所有Kconfig*�置文件�说，它们缩进方�与C代�相比有所��。紧挨
	在“config�定义下�的行缩进一个制表符，帮助信�则�多缩进2个空格。比如：
	
	config AUDIT
		bool "Auditing support"
		depends on NET
		help
		  Enable auditing infrastructure that can be used with another
		  kernel subsystem, such as SELinux (which requires this for
		  logging of avc messages output).  Does not do system-call
		  auditing without CONFIG_AUDITSYSCALL.
	
	�然被认为�够稳定的功能应该被定义为�赖于“EXPERIMENTAL�：
	
	config SLUB
		depends on EXPERIMENTAL && !ARCH_USES_SLAB_PAGE_STRUCT
		bool "SLUB (Unqueued Allocator)"
		...
	
	而那些�险的功能（比如�些文件系统的写支�）应该在它们的�示字符串里显著的声明这
	一点：
	
	config ADFS_FS_RW
		bool "ADFS write support (DANGEROUS)"
		depends on ADFS_FS
		...
	
	�查看�置文件的完整文档，请看Documentation/kbuild/kconfig-language.txt。
	
	
			第�一章：数�结构
	
	如果一个数�结构，在创建和销�它的�线执行环境之外��，那么它必须�有一个引用计
	数器。内核里没有垃圾收集（并且内核之外的垃圾收集慢且效率低下），这�味�你�对需
	�记录你对这�数�结构的使用情况。
	
	引用计数�味�你能够��上�，并且�许多个用户并行访问这个数�结构——而�需�担心
	这个数�结构仅仅因为暂时�被使用就消失了，那些用户�能�过是沉�了一阵或者�了一
	些其他事情而已。
	
	注�上��能�代引用计数。上�是为了��数�结构的一致性，而引用计数是一个内存管
	�技巧。通常二者都需�，��把两个�混了。
	
	很多数�结构实际上有2级引用计数，它们通常有��“类�的用户。�类计数器统计�类用
	户的数�，�当�类计数器�至零时，全局计数器�一。
	
	这�“多级引用计数�的例��以在内存管�（“struct mm_struct�：mm_users和mm_count）
	和文件系统（“struct super_block�：s_count和s_active）中找到。
	
	记�：如果�一个执行线索�以找到你的数�结构，但是这个数�结构没有引用计数器，这
	里几乎肯定是一个bug。
	
	
			第�二章：�，枚举和RTL
	
	用于定义常�的�的�字�枚举里的标签需�大写。
	
	#define CONSTANT 0x12345
	
	在定义几个相关的常�时，最好用枚举。
	
	�的�字请用大写字�，�过形如函数的�的�字�以用�写字�。
	
	一般的，如果能写�内�函数就��写��函数的�。
	
	�有多个语�的�应该被包�在一个do-while代��里：
	
	#define macrofun(a, b, c) 			\
		do {					\
			if (a == 5)			\
				do_this(b, c);		\
		} while (0)
	
	使用�的时候应��的事情：
	
	1) 影�控制�程的�：
	
	#define FOO(x)					\
		do {					\
			if (blah(x) < 0)		\
				return -EBUGGERED;	\
		} while(0)
	
	�常�好。它看起��一个函数，�过�能导致“调用�它的函数退出；��打乱读者大脑里
	的语法分�器。
	
	2) �赖于一个固定�字的本地��的�：
	
	#define FOO(val) bar(index, val)
	
	�能看起��是个�错的东西，�过它�常容易把读代�的人�糊涂，而且容易导致看起�
	�相关的改动带�错误。
	
	3) 作为左值的带�数的�： FOO(x) = y；如果有人把FOO��一个内�函数的�，这�用
	法就会出错了。
	
	4) 忘记了优先级：使用表达�定义常�的�必须将表达�置于一对�括�之内。带�数的
	�也�注�此类问题。
	
	#define CONSTANT 0x4000
	#define CONSTEXP (CONSTANT | 3)
	
	cpp手册对�的讲解很详细。Gcc internals手册也详细讲解了RTL（译注：register
	transfer language），内核里的汇编语言�常用到它。
	
	
			第�三章：打�内核消�
	
	内核开�者应该是�过良好教育的。请一定注�内核信�的拼写，以给人以好的�象。��
	用�规范的��比如“dont�，而�用“do not�或者“don't�。��这些信�简��明了�无
	歧义。
	
	内核信��必以��（译注：英文��，�点）结�。
	
	在�括�里打�数字(%d)没有任何价值，应该��这样�。
	
	<linux/device.h>里有一些驱动模型诊断�，你应该使用它们，以确�信�对应于正确的
	设备和驱动，并且被标记了正确的消�级别。这些�有：dev_err(), dev_warn(),
	dev_info()等等。对于那些�和�个特定设备相关连的信�，<linux/kernel.h>定义了
	pr_debug()和pr_info()。
	
	写出好的调试信��以是一个很大的挑战；当你写出�之�，这些信�在远程除错的时候
	就会�为�大的帮助。当DEBUG符�没有被定义的时候，这些信��应该被编译进内核里
	（也就是说，默认地，它们�应该被包�在内）。如果你使用dev_dbg()或者pr_debug()，
	就能自动达到这个效果。很多�系统拥有Kconfig选项��用-DDEBUG。还有一个相关的惯例
	是使用VERBOSE_DEBUG�添加dev_vdbg()消�到那些已�由DEBUG�用的消�之上。
	
	
			第�四章：分�内存
	
	内核�供了下�的一般用途的内存分�函数：kmalloc()，kzalloc()，kcalloc()和
	vmalloc()。请�考API文档以获�有关它们的详细