About Kernel Documentation Linux Kernel Contact Linux Resources Linux Blog

Documentation / zh_CN / CodingStyle


Based on kernel version 4.9. Page generated on 2016-12-21 14:37 EST.

1	Chinese translated version of Documentation/CodingStyle
2	
3	If you have any comment or update to the content, please post to LKML directly.
4	However, if you have problem communicating in English you can also ask the
5	Chinese maintainer for help.  Contact the Chinese maintainer, if this
6	translation is outdated or there is problem with translation.
7	
8	Chinese maintainer: Zhang Le <r0bertz@gentoo.org>
9	---------------------------------------------------------------------
10	Documentation/CodingStyle的中文翻译
11	
12	如果想评论或更新本文的内容,请直接发信到LKML。如果你使用英文交流有困难的话,也可
13	以向中文版维护者求助。如果本翻译更新不及时或者翻译存在问题,请联系中文版维护者。
14	
15	中文版维护者: 张乐 Zhang Le <r0bertz@gentoo.org>
16	中文版翻译者: 张乐 Zhang Le <r0bertz@gentoo.org>
17	中文版校译者: 王聪 Wang Cong <xiyou.wangcong@gmail.com>
18	               wheelz <kernel.zeng@gmail.com>
19	               管旭东 Xudong Guan <xudong.guan@gmail.com>
20	               Li Zefan <lizf@cn.fujitsu.com>
21	               Wang Chen <wangchen@cn.fujitsu.com>
22	以下为正文
23	---------------------------------------------------------------------
24	
25			Linux内核代码风格
26	
27	这是一个简短的文档,描述了 linux 内核的首选代码风格。代码风格是因人而异的,而且我
28	不愿意把自己的观点强加给任何人,但这就像我去做任何事情都必须遵循的原则那样,我也
29	希望在绝大多数事上保持这种的态度。请(在写代码时)至少考虑一下这里的代码风格。
30	
31	首先,我建议你打印一份 GNU 代码规范,然后不要读。烧了它,这是一个具有重大象征性意义
32	的动作。
33	
34	不管怎样,现在我们开始:
35	
36	
37			第一章:缩进
38	
39	制表符是 8 个字符,所以缩进也是 8 个字符。有些异端运动试图将缩进变为 4(甚至 2!)
40	个字符深,这几乎相当于尝试将圆周率的值定义为 3。
41	
42	理由:缩进的全部意义就在于清楚的定义一个控制块起止于何处。尤其是当你盯着你的屏幕
43	连续看了 20 小时之后,你将会发现大一点的缩进会使你更容易分辨缩进。
44	
45	现在,有些人会抱怨 8 个字符的缩进会使代码向右边移动的太远,在 80 个字符的终端屏幕上
46	就很难读这样的代码。这个问题的答案是,如果你需要 3 级以上的缩进,不管用何种方式你
47	的代码已经有问题了,应该修正你的程序。
48	
49	简而言之,8 个字符的缩进可以让代码更容易阅读,还有一个好处是当你的函数嵌套太深的
50	时候可以给你警告。留心这个警告。
51	
52	在 switch 语句中消除多级缩进的首选的方式是让 “switch” 和从属于它的 “case” 标签
53	对齐于同一列,而不要 “两次缩进” “case” 标签。比如:
54	
55		switch (suffix) {
56		case 'G':
57		case 'g':
58			mem <<= 30;
59			break;
60		case 'M':
61		case 'm':
62			mem <<= 20;
63			break;
64		case 'K':
65		case 'k':
66			mem <<= 10;
67			/* fall through */
68		default:
69			break;
70		}
71	
72	不要把多个语句放在一行里,除非你有什么东西要隐藏:
73	
74		if (condition) do_this;
75		  do_something_everytime;
76	
77	也不要在一行里放多个赋值语句。内核代码风格超级简单。就是避免可能导致别人误读的表
78	达式。
79	
80	除了注释、文档和 Kconfig 之外,不要使用空格来缩进,前面的例子是例外,是有意为之。
81	
82	选用一个好的编辑器,不要在行尾留空格。
83	
84	
85			第二章:把长的行和字符串打散
86	
87	代码风格的意义就在于使用平常使用的工具来维持代码的可读性和可维护性。
88	
89	每一行的长度的限制是 80 列,我们强烈建议您遵守这个惯例。
90	
91	长于 80 列的语句要打散成有意义的片段。除非超过 80 列能显著增加可读性,并且不会隐藏
92	信息。子片段要明显短于母片段,并明显靠右。这同样适用于有着很长参数列表的函数头。
93	然而,绝对不要打散对用户可见的字符串,例如 printk 信息,因为这将导致无法 grep 这些
94	信息。
95	
96			第三章:大括号和空格的放置
97	
98	C语言风格中另外一个常见问题是大括号的放置。和缩进大小不同,选择或弃用某种放置策
99	略并没有多少技术上的原因,不过首选的方式,就像 Kernighan 和 Ritchie 展示给我们的,
100	是把起始大括号放在行尾,而把结束大括号放在行首,所以:
101	
102		if (x is true) {
103			we do y
104		}
105	
106	这适用于所有的非函数语句块(if、switch、for、while、do)。比如:
107	
108		switch (action) {
109		case KOBJ_ADD:
110			return "add";
111		case KOBJ_REMOVE:
112			return "remove";
113		case KOBJ_CHANGE:
114			return "change";
115		default:
116			return NULL;
117		}
118	
119	不过,有一个例外,那就是函数:函数的起始大括号放置于下一行的开头,所以:
120	
121		int function(int x)
122		{
123			body of function
124		}
125	
126	全世界的异端可能会抱怨这个不一致性是……呃……不一致的,不过所有思维健全的人都知道
127	(a) K&R 是 _正确的_,并且 (b) K&R 是正确的。此外,不管怎样函数都是特殊的(C
128	函数是不能嵌套的)。
129	
130	注意结束大括号独自占据一行,除非它后面跟着同一个语句的剩余部分,也就是 do 语句中的
131	“while” 或者 if 语句中的 “else”,像这样:
132	
133		do {
134			body of do-loop
135		} while (condition);
136	
137	138	
139		if (x == y) {
140			..
141		} else if (x > y) {
142			...
143		} else {
144			....
145		}
146	
147	理由:K&R。
148	
149	也请注意这种大括号的放置方式也能使空(或者差不多空的)行的数量最小化,同时不失可
150	读性。因此,由于你的屏幕上的新行是不可再生资源(想想 25 行的终端屏幕),你将会有更
151	多的空行来放置注释。
152	
153	当只有一个单独的语句的时候,不用加不必要的大括号。
154	
155		if (condition)
156			action();
157	
158	159	
160		if (condition)
161			do_this();
162		else
163			do_that();
164	
165	这并不适用于只有一个条件分支是单语句的情况;这时所有分支都要使用大括号:
166	
167		if (condition) {
168			do_this();
169			do_that();
170		} else {
171			otherwise();
172		}
173	
174			3.1:空格
175	
176	Linux 内核的空格使用方式(主要)取决于它是用于函数还是关键字。(大多数)关键字后
177	要加一个空格。值得注意的例外是 sizeof、typeof、alignof 和 __attribute__,这些
178	关键字某些程度上看起来更像函数(它们在 Linux 里也常常伴随小括号而使用,尽管在 C 里
179	这样的小括号不是必需的,就像 “struct fileinfo info” 声明过后的 “sizeof info”)。
180	
181	所以在这些关键字之后放一个空格:
182	
183		if, switch, case, for, do, while
184	
185	但是不要在 sizeof、typeof、alignof 或者 __attribute__ 这些关键字之后放空格。例如,
186	
187		s = sizeof(struct file);
188	
189	不要在小括号里的表达式两侧加空格。这是一个反例:
190	
191		s = sizeof( struct file );
192	
193	当声明指针类型或者返回指针类型的函数时,“*” 的首选使用方式是使之靠近变量名或者函
194	数名,而不是靠近类型名。例子:
195	
196		char *linux_banner;
197		unsigned long long memparse(char *ptr, char **retptr);
198		char *match_strdup(substring_t *s);
199	
200	在大多数二元和三元操作符两侧使用一个空格,例如下面所有这些操作符:
201	
202		=  +  -  <  >  *  /  %  |  &  ^  <=  >=  ==  !=  ?  :
203	
204	但是一元操作符后不要加空格:
205	
206		&  *  +  -  ~  !  sizeof  typeof  alignof  __attribute__  defined
207	
208	后缀自加和自减一元操作符前不加空格:
209	
210		++  --
211	
212	前缀自加和自减一元操作符后不加空格:
213	
214		++  --
215	
216	‘.’ 和 “->” 结构体成员操作符前后不加空格。
217	
218	不要在行尾留空白。有些可以自动缩进的编辑器会在新行的行首加入适量的空白,然后你
219	就可以直接在那一行输入代码。不过假如你最后没有在那一行输入代码,有些编辑器就不
220	会移除已经加入的空白,就像你故意留下一个只有空白的行。包含行尾空白的行就这样产
221	生了。
222	
223	当git发现补丁包含了行尾空白的时候会警告你,并且可以应你的要求去掉行尾空白;不过
224	如果你是正在打一系列补丁,这样做会导致后面的补丁失败,因为你改变了补丁的上下文。
225	
226	
227			第四章:命名
228	
229	C是一个简朴的语言,你的命名也应该这样。和 Modula-2 和 Pascal 程序员不同,C 程序员
230	不使用类似 ThisVariableIsATemporaryCounter 这样华丽的名字。C 程序员会称那个变量
231	为 “tmp”,这样写起来会更容易,而且至少不会令其难于理解。
232	
233	不过,虽然混用大小写的名字是不提倡使用的,但是全局变量还是需要一个具描述性的名字
234	。称一个全局函数为 “foo” 是一个难以饶恕的错误。
235	
236	全局变量(只有当你真正需要它们的时候再用它)需要有一个具描述性的名字,就像全局函
237	数。如果你有一个可以计算活动用户数量的函数,你应该叫它 “count_active_users()”
238	或者类似的名字,你不应该叫它 “cntuser()”。
239	
240	在函数名中包含函数类型(所谓的匈牙利命名法)是脑子出了问题——编译器知道那些类型而
241	且能够检查那些类型,这样做只能把程序员弄糊涂了。难怪微软总是制造出有问题的程序。
242	
243	本地变量名应该简短,而且能够表达相关的含义。如果你有一些随机的整数型的循环计数器
244	,它应该被称为 “i”。叫它 “loop_counter” 并无益处,如果它没有被误解的可能的话。
245	类似的,“tmp” 可以用来称呼任意类型的临时变量。
246	
247	如果你怕混淆了你的本地变量名,你就遇到另一个问题了,叫做函数增长荷尔蒙失衡综合症
248	。请看第六章(函数)。
249	
250	
251			第五章:Typedef
252	
253	不要使用类似 “vps_t” 之类的东西。
254	
255	对结构体和指针使用 typedef 是一个错误。当你在代码里看到:
256	
257		vps_t a;
258	
259	这代表什么意思呢?
260	
261	相反,如果是这样
262	
263		struct virtual_container *a;
264	
265	你就知道 “a” 是什么了。
266	
267	很多人认为 typedef “能提高可读性”。实际不是这样的。它们只在下列情况下有用:
268	
269	 (a) 完全不透明的对象(这种情况下要主动使用 typedef 来隐藏这个对象实际上是什么)。
270	
271	     例如:“pte_t” 等不透明对象,你只能用合适的访问函数来访问它们。
272	
273	     注意!不透明性和“访问函数”本身是不好的。我们使用 pte_t 等类型的原因在于真的是
274	     完全没有任何共用的可访问信息。
275	
276	 (b) 清楚的整数类型,如此,这层抽象就可以帮助消除到底是 “int” 还是 “long” 的混淆。
277	
278	     u8/u16/u32 是完全没有问题的 typedef,不过它们更符合类别 (d) 而不是这里。
279	
280	     再次注意!要这样做,必须事出有因。如果某个变量是 “unsigned long“,那么没有必要
281	
282		typedef unsigned long myflags_t;
283	
284	     不过如果有一个明确的原因,比如它在某种情况下可能会是一个 “unsigned int” 而在
285	     其他情况下可能为 “unsigned long”,那么就不要犹豫,请务必使用 typedef。
286	
287	 (c) 当你使用sparse按字面的创建一个新类型来做类型检查的时候。
288	
289	 (d) 和标准C99类型相同的类型,在某些例外的情况下。
290	
291	     虽然让眼睛和脑筋来适应新的标准类型比如 “uint32_t” 不需要花很多时间,可是有些
292	     人仍然拒绝使用它们。
293	
294	     因此,Linux 特有的等同于标准类型的 “u8/u16/u32/u64” 类型和它们的有符号类型是被
295	     允许的——尽管在你自己的新代码中,它们不是强制要求要使用的。
296	
297	     当编辑已经使用了某个类型集的已有代码时,你应该遵循那些代码中已经做出的选择。
298	
299	 (e) 可以在用户空间安全使用的类型。
300	
301	     在某些用户空间可见的结构体里,我们不能要求C99类型而且不能用上面提到的 “u32”
302	     类型。因此,我们在与用户空间共享的所有结构体中使用 __u32 和类似的类型。
303	
304	可能还有其他的情况,不过基本的规则是永远不要使用 typedef,除非你可以明确的应用上
305	述某个规则中的一个。
306	
307	总的来说,如果一个指针或者一个结构体里的元素可以合理的被直接访问到,那么它们就不
308	应该是一个 typedef。
309	
310	
311			第六章:函数
312	
313	函数应该简短而漂亮,并且只完成一件事情。函数应该可以一屏或者两屏显示完(我们都知
314	道 ISO/ANSI 屏幕大小是 80x24),只做一件事情,而且把它做好。
315	
316	一个函数的最大长度是和该函数的复杂度和缩进级数成反比的。所以,如果你有一个理论上
317	很简单的只有一个很长(但是简单)的 case 语句的函数,而且你需要在每个 case 里做
318	很多很小的事情,这样的函数尽管很长,但也是可以的。
319	
320	不过,如果你有一个复杂的函数,而且你怀疑一个天分不是很高的高中一年级学生可能甚至
321	搞不清楚这个函数的目的,你应该严格的遵守前面提到的长度限制。使用辅助函数,并为之
322	取个具描述性的名字(如果你觉得它们的性能很重要的话,可以让编译器内联它们,这样的
323	效果往往会比你写一个复杂函数的效果要好。)
324	
325	函数的另外一个衡量标准是本地变量的数量。此数量不应超过 5-10 个,否则你的函数就有
326	问题了。重新考虑一下你的函数,把它分拆成更小的函数。人的大脑一般可以轻松的同时跟
327	踪 7 个不同的事物,如果再增多的话,就会糊涂了。即便你聪颖过人,你也可能会记不清你
328	2 个星期前做过的事情。
329	
330	在源文件里,使用空行隔开不同的函数。如果该函数需要被导出,它的 EXPORT* 宏应该紧贴
331	在它的结束大括号之下。比如:
332	
333		int system_is_up(void)
334		{
335			return system_state == SYSTEM_RUNNING;
336		}
337		EXPORT_SYMBOL(system_is_up);
338	
339	在函数原型中,包含函数名和它们的数据类型。虽然C语言里没有这样的要求,在 Linux 里这
340	是提倡的做法,因为这样可以很简单的给读者提供更多的有价值的信息。
341	
342	
343			第七章:集中的函数退出途径
344	
345	虽然被某些人声称已经过时,但是 goto 语句的等价物还是经常被编译器所使用,具体形式是
346	无条件跳转指令。
347	
348	当一个函数从多个位置退出,并且需要做一些类似清理的常见操作时,goto 语句就很方便了。
349	如果并不需要清理操作,那么直接 return 即可。
350	
351	理由是:
352	
353	- 无条件语句容易理解和跟踪
354	- 嵌套程度减小
355	- 可以避免由于修改时忘记更新某个单独的退出点而导致的错误
356	- 减轻了编译器的工作,无需删除冗余代码;)
357	
358		int fun(int a)
359		{
360			int result = 0;
361			char *buffer;
362	
363			buffer = kmalloc(SIZE, GFP_KERNEL);
364			if (!buffer)
365				return -ENOMEM;
366	
367			if (condition1) {
368				while (loop1) {
369					...
370				}
371				result = 1;
372				goto out_buffer;
373			}
374			...
375		out_buffer:
376			kfree(buffer);
377			return result;
378		}
379	
380	一个需要注意的常见错误是“一个 err 错误”,就像这样:
381	
382		err:
383			kfree(foo->bar);
384			kfree(foo);
385			return ret;
386	
387	这段代码的错误是,在某些退出路径上 “foo” 是 NULL。通常情况下,通过把它分离成两个
388	错误标签 “err_bar:” 和 “err_foo:” 来修复这个错误。
389	
390			第八章:注释
391	
392	注释是好的,不过有过度注释的危险。永远不要在注释里解释你的代码是如何运作的:更好
393	的做法是让别人一看你的代码就可以明白,解释写的很差的代码是浪费时间。
394	
395	一般的,你想要你的注释告诉别人你的代码做了什么,而不是怎么做的。也请你不要把注释
396	放在一个函数体内部:如果函数复杂到你需要独立的注释其中的一部分,你很可能需要回到
397	第六章看一看。你可以做一些小注释来注明或警告某些很聪明(或者槽糕)的做法,但不要
398	加太多。你应该做的,是把注释放在函数的头部,告诉人们它做了什么,也可以加上它做这
399	些事情的原因。
400	
401	当注释内核API函数时,请使用 kernel-doc 格式。请看
402	Documentation/kernel-documentation.rst和scripts/kernel-doc 以获得详细信息。
403	
404	Linux的注释风格是 C89 “/* ... */” 风格。不要使用 C99 风格 “// ...” 注释。
405	
406	长(多行)的首选注释风格是:
407	
408		/*
409		 * This is the preferred style for multi-line
410		 * comments in the Linux kernel source code.
411		 * Please use it consistently.
412		 *
413		 * Description:  A column of asterisks on the left side,
414		 * with beginning and ending almost-blank lines.
415		 */
416	
417	对于在 net/ 和 drivers/net/ 的文件,首选的长(多行)注释风格有些不同。
418	
419		/* The preferred comment style for files in net/ and drivers/net
420		 * looks like this.
421		 *
422		 * It is nearly the same as the generally preferred comment style,
423		 * but there is no initial almost-blank line.
424		 */
425	
426	注释数据也是很重要的,不管是基本类型还是衍生类型。为了方便实现这一点,每一行应只
427	声明一个数据(不要使用逗号来一次声明多个数据)。这样你就有空间来为每个数据写一段
428	小注释来解释它们的用途了。
429	
430	
431			第九章:你已经把事情弄糟了
432	
433	这没什么,我们都是这样。可能你的使用了很长时间 Unix 的朋友已经告诉你 “GNU emacs” 能
434	自动帮你格式化 C 源代码,而且你也注意到了,确实是这样,不过它所使用的默认值和我们
435	想要的相去甚远(实际上,甚至比随机打的还要差——无数个猴子在 GNU emacs 里打字永远不
436	会创造出一个好程序)(译注:请参考 Infinite Monkey Theorem)
437	
438	所以你要么放弃 GNU emacs,要么改变它让它使用更合理的设定。要采用后一个方案,你可
439	以把下面这段粘贴到你的 .emacs 文件里。
440	
441	(defun c-lineup-arglist-tabs-only (ignored)
442	  "Line up argument lists by tabs, not spaces"
443	  (let* ((anchor (c-langelem-pos c-syntactic-element))
444	         (column (c-langelem-2nd-pos c-syntactic-element))
445	         (offset (- (1+ column) anchor))
446	         (steps (floor offset c-basic-offset)))
447	    (* (max steps 1)
448	       c-basic-offset)))
449	
450	(add-hook 'c-mode-common-hook
451	          (lambda ()
452	            ;; Add kernel style
453	            (c-add-style
454	             "linux-tabs-only"
455	             '("linux" (c-offsets-alist
456	                        (arglist-cont-nonempty
457	                         c-lineup-gcc-asm-reg
458	                         c-lineup-arglist-tabs-only))))))
459	
460	(add-hook 'c-mode-hook
461	          (lambda ()
462	            (let ((filename (buffer-file-name)))
463	              ;; Enable kernel mode for the appropriate files
464	              (when (and filename
465	                         (string-match (expand-file-name "~/src/linux-trees")
466	                                       filename))
467	                (setq indent-tabs-mode t)
468	                (setq show-trailing-whitespace t)
469	                (c-set-style "linux-tabs-only")))))
470	
471	这会让 emacs 在 ~/src/linux-trees 目录下的 C 源文件获得更好的内核代码风格。
472	
473	不过就算你尝试让 emacs 正确的格式化代码失败了,也并不意味着你失去了一切:还可以用
474	“indent”。
475	
476	不过,GNU indent 也有和 GNU emacs 一样有问题的设定,所以你需要给它一些命令选项。不
477	过,这还不算太糟糕,因为就算是 GNU indent 的作者也认同 K&R 的权威性(GNU 的人并不是
478	坏人,他们只是在这个问题上被严重的误导了),所以你只要给 indent 指定选项 “-kr -i8”
479	(代表 “K&R,8 个字符缩进”),或者使用 “scripts/Lindent”,这样就可以以最时髦的方式
480	缩进源代码。
481	
482	“indent” 有很多选项,特别是重新格式化注释的时候,你可能需要看一下它的手册页。不过
483	记住:“indent” 不能修正坏的编程习惯。
484	
485	
486			第十章:Kconfig 配置文件
487	
488	对于遍布源码树的所有 Kconfig* 配置文件来说,它们缩进方式与 C 代码相比有所不同。紧挨
489	在 “config” 定义下面的行缩进一个制表符,帮助信息则再多缩进 2 个空格。比如:
490	
491	config AUDIT
492		bool "Auditing support"
493		depends on NET
494		help
495		  Enable auditing infrastructure that can be used with another
496		  kernel subsystem, such as SELinux (which requires this for
497		  logging of avc messages output).  Does not do system-call
498		  auditing without CONFIG_AUDITSYSCALL.
499	
500	而那些危险的功能(比如某些文件系统的写支持)应该在它们的提示字符串里显著的声明这
501	一点:
502	
503	config ADFS_FS_RW
504		bool "ADFS write support (DANGEROUS)"
505		depends on ADFS_FS
506		...
507	
508	要查看配置文件的完整文档,请看 Documentation/kbuild/kconfig-language.txt。
509	
510	
511			第十一章:数据结构
512	
513	如果一个数据结构,在创建和销毁它的单线执行环境之外可见,那么它必须要有一个引用计
514	数器。内核里没有垃圾收集(并且内核之外的垃圾收集慢且效率低下),这意味着你绝对需
515	要记录你对这种数据结构的使用情况。
516	
517	引用计数意味着你能够避免上锁,并且允许多个用户并行访问这个数据结构——而不需要担心
518	这个数据结构仅仅因为暂时不被使用就消失了,那些用户可能不过是沉睡了一阵或者做了一
519	些其他事情而已。
520	
521	注意上锁不能取代引用计数。上锁是为了保持数据结构的一致性,而引用计数是一个内存管
522	理技巧。通常二者都需要,不要把两个搞混了。
523	
524	很多数据结构实际上有2级引用计数,它们通常有不同“类”的用户。子类计数器统计子类用
525	户的数量,每当子类计数器减至零时,全局计数器减一。
526	
527	这种“多级引用计数”的例子可以在内存管理(“struct mm_struct”:mm_users 和 mm_count)
528	和文件系统(“struct super_block”:s_count和s_active)中找到。
529	
530	记住:如果另一个执行线索可以找到你的数据结构,但是这个数据结构没有引用计数器,这
531	里几乎肯定是一个 bug。
532	
533	
534			第十二章:宏,枚举和RTL
535	
536	用于定义常量的宏的名字及枚举里的标签需要大写。
537	
538	#define CONSTANT 0x12345
539	
540	在定义几个相关的常量时,最好用枚举。
541	
542	宏的名字请用大写字母,不过形如函数的宏的名字可以用小写字母。
543	
544	一般的,如果能写成内联函数就不要写成像函数的宏。
545	
546	含有多个语句的宏应该被包含在一个 do-while 代码块里:
547	
548		#define macrofun(a, b, c)			\
549			do {					\
550				if (a == 5)			\
551					do_this(b, c);		\
552			} while (0)
553	
554	使用宏的时候应避免的事情:
555	
556	1) 影响控制流程的宏:
557	
558		#define FOO(x)					\
559			do {					\
560				if (blah(x) < 0)		\
561					return -EBUGGERED;	\
562			} while (0)
563	
564	非常不好。它看起来像一个函数,不过却能导致“调用”它的函数退出;不要打乱读者大脑里
565	的语法分析器。
566	
567	2) 依赖于一个固定名字的本地变量的宏:
568	
569		#define FOO(val) bar(index, val)
570	
571	可能看起来像是个不错的东西,不过它非常容易把读代码的人搞糊涂,而且容易导致看起来
572	不相关的改动带来错误。
573	
574	3) 作为左值的带参数的宏: FOO(x) = y;如果有人把 FOO 变成一个内联函数的话,这种用
575	法就会出错了。
576	
577	4) 忘记了优先级:使用表达式定义常量的宏必须将表达式置于一对小括号之内。带参数的
578	宏也要注意此类问题。
579	
580		#define CONSTANT 0x4000
581		#define CONSTEXP (CONSTANT | 3)
582	
583	5) 在宏里定义类似函数的本地变量时命名冲突:
584	
585		#define FOO(x)				\
586		({					\
587			typeof(x) ret;			\
588			ret = calc_ret(x);		\
589			(ret);				\
590		})
591	
592	ret 是本地变量的通用名字 - __foo_ret 更不容易与一个已存在的变量冲突。
593	
594	cpp 手册对宏的讲解很详细。gcc internals 手册也详细讲解了 RTL(译注:register
595	transfer language),内核里的汇编语言经常用到它。
596	
597	
598			第十三章:打印内核消息
599	
600	内核开发者应该是受过良好教育的。请一定注意内核信息的拼写,以给人以好的印象。不要
601	用不规范的单词比如 “dont”,而要用 “do not”或者 “don't”。保证这些信息简单、明了、
602	无歧义。
603	
604	内核信息不必以句号(译注:英文句号,即点)结束。
605	
606	在小括号里打印数字 (%d) 没有任何价值,应该避免这样做。
607	
608	<linux/device.h> 里有一些驱动模型诊断宏,你应该使用它们,以确保信息对应于正确的
609	设备和驱动,并且被标记了正确的消息级别。这些宏有:dev_err(),dev_warn(),
610	dev_info() 等等。对于那些不和某个特定设备相关连的信息,<linux/printk.h> 定义了
611	pr_notice(),pr_info(),pr_warn(),pr_err() 和其他。
612	
613	写出好的调试信息可以是一个很大的挑战;一旦你写出后,这些信息在远程除错时能提供极大
614	的帮助。然而打印调试信息的处理方式同打印非调试信息不同。其他 pr_XXX() 函数能无条件地
615	打印,pr_debug() 却不;默认情况下它不会被编译,除非定义了 DEBUG 或设定了
616	CONFIG_DYNAMIC_DEBUG。实际这同样是为了 dev_dbg(),一个相关约定是在一个已经开启了
617	DEBUG 时,使用 VERBOSE_DEBUG 来添加 dev_vdbg()。
618	
619	许多子系统拥有 Kconfig 调试选项来开启 -DDEBUG 在对应的 Makefile 里面;在其他
620	情况下,特殊文件使用 #define DEBUG。当一条调试信息需要被无条件打印时,例如,如果
621	已经包含一个调试相关的 #ifdef 条件,printk(KERN_DEBUG ...) 就可被使用。
622	
623	
624			第十四章:分配内存
625	
626	内核提供了下面的一般用途的内存分配函数:
627	kmalloc(),kzalloc(),kmalloc_array(),kcalloc(),vmalloc() 和 vzalloc()。
628	请参考 API 文档以获取有关它们的详细信息。
629	
630	传递结构体大小的首选形式是这样的:
631	
632		p = kmalloc(sizeof(*p), ...);
633	
634	另外一种传递方式中,sizeof 的操作数是结构体的名字,这样会降低可读性,并且可能会引
635	入 bug。有可能指针变量类型被改变时,而对应的传递给内存分配函数的 sizeof 的结果不变。
636	
637	强制转换一个 void 指针返回值是多余的。C 语言本身保证了从 void 指针到其他任何指针类型
638	的转换是没有问题的。
639	
640	分配一个数组的首选形式是这样的:
641	
642		p = kmalloc_array(n, sizeof(...), ...);
643	
644	分配一个零长数组的首选形式是这样的:
645	
646		p = kcalloc(n, sizeof(...), ...);
647	
648	两种形式检查分配大小 n * sizeof(...) 的溢出,如果溢出返回 NULL。
649	
650	
651			第十五章:内联弊病
652	
653	有一个常见的误解是内联函数是 gcc 提供的可以让代码运行更快的一个选项。虽然使用内联
654	函数有时候是恰当的(比如作为一种替代宏的方式,请看第十二章),不过很多情况下不是
655	这样。inline 关键字的过度使用会使内核变大,从而使整个系统运行速度变慢。因为大内核
656	会占用更多的指令高速缓存(译注:一级缓存通常是指令缓存和数据缓存分开的)而且会导
657	致 pagecache 的可用内存减少。想象一下,一次pagecache未命中就会导致一次磁盘寻址,
658	将耗时 5 毫秒。5 毫秒的时间内 CPU 能执行很多很多指令。
659	
660	一个基本的原则是如果一个函数有 3 行以上,就不要把它变成内联函数。这个原则的一个例
661	外是,如果你知道某个参数是一个编译时常量,而且因为这个常量你确定编译器在编译时能
662	优化掉你的函数的大部分代码,那仍然可以给它加上 inline 关键字。kmalloc() 内联函数就
663	是一个很好的例子。
664	
665	人们经常主张给 static 的而且只用了一次的函数加上 inline,如此不会有任何损失,因为没
666	有什么好权衡的。虽然从技术上说这是正确的,但是实际上这种情况下即使不加 inline gcc
667	也可以自动使其内联。而且其他用户可能会要求移除 inline,由此而来的争论会抵消 inline
668	自身的潜在价值,得不偿失。
669	
670	
671			第十六章:函数返回值及命名
672	
673	函数可以返回很多种不同类型的值,最常见的一种是表明函数执行成功或者失败的值。这样
674	的一个值可以表示为一个错误代码整数(-Exxx=失败,0=成功)或者一个“成功”布尔值(
675	0=失败,非0=成功)。
676	
677	混合使用这两种表达方式是难于发现的 bug 的来源。如果 C 语言本身严格区分整形和布尔型变
678	量,那么编译器就能够帮我们发现这些错误……不过 C 语言不区分。为了避免产生这种 bug,请
679	遵循下面的惯例:
680	
681		如果函数的名字是一个动作或者强制性的命令,那么这个函数应该返回错误代码整
682		数。如果是一个判断,那么函数应该返回一个“成功”布尔值。
683	
684	比如,“add work” 是一个命令,所以 add_work() 函数在成功时返回 0,在失败时返回 -EBUSY。
685	类似的,因为 “PCI device present” 是一个判断,所以 pci_dev_present() 函数在成功找到
686	一个匹配的设备时应该返回 1,如果找不到时应该返回 0。
687	
688	所有导出(译注:EXPORT)的函数都必须遵守这个惯例,所有的公共函数也都应该如此。私
689	有(static)函数不需要如此,但是我们也推荐这样做。
690	
691	返回值是实际计算结果而不是计算是否成功的标志的函数不受此惯例的限制。一般的,他们
692	通过返回一些正常值范围之外的结果来表示出错。典型的例子是返回指针的函数,他们使用
693	NULL 或者 ERR_PTR 机制来报告错误。
694	
695	
696			第十七章:不要重新发明内核宏
697	
698	头文件 include/linux/kernel.h 包含了一些宏,你应该使用它们,而不要自己写一些它们的
699	变种。比如,如果你需要计算一个数组的长度,使用这个宏
700	
701		#define ARRAY_SIZE(x) (sizeof(x) / sizeof((x)[0]))
702	
703	类似的,如果你要计算某结构体成员的大小,使用
704	
705		#define FIELD_SIZEOF(t, f) (sizeof(((t*)0)->f))
706	
707	还有可以做严格的类型检查的 min() 和 max() 宏,如果你需要可以使用它们。你可以自己看看
708	那个头文件里还定义了什么你可以拿来用的东西,如果有定义的话,你就不应在你的代码里
709	自己重新定义。
710	
711	
712			第十八章:编辑器模式行和其他需要罗嗦的事情
713	
714	有一些编辑器可以解释嵌入在源文件里的由一些特殊标记标明的配置信息。比如,emacs
715	能够解释被标记成这样的行:
716	
717		-*- mode: c -*-
718	
719	或者这样的:
720	
721		/*
722		Local Variables:
723		compile-command: "gcc -DMAGIC_DEBUG_FLAG foo.c"
724		End:
725		*/
726	
727	Vim 能够解释这样的标记:
728	
729		/* vim:set sw=8 noet */
730	
731	不要在源代码中包含任何这样的内容。每个人都有他自己的编辑器配置,你的源文件不应
732	该覆盖别人的配置。这包括有关缩进和模式配置的标记。人们可以使用他们自己定制的模
733	式,或者使用其他可以产生正确的缩进的巧妙方法。
734	
735	
736			第十九章:内联汇编
737	
738	在特定架构的代码中,你也许需要内联汇编来使用 CPU 接口和平台相关功能。在需要
739	这么做时,不要犹豫。然而,当 C 可以完成工作时,不要无端地使用内联汇编。如果
740	可能,你可以并且应该用 C 和硬件交互。
741	
742	考虑去写通用一点的内联汇编作为简明的辅助函数,而不是重复写下它们的细节。记住
743	内联汇编可以使用 C 参数。
744	
745	大而特殊的汇编函数应该放在 .S 文件中,对应 C 的原型定义在 C 头文件中。汇编
746	函数的 C 原型应该使用 “asmlinkage”。
747	
748	你可能需要将你的汇编语句标记为 volatile,来阻止 GCC 在没发现任何副作用后就
749	移除了它。你不必总是这样做,虽然,这样可以限制不必要的优化。
750	
751	在写一个包含多条指令的单个内联汇编语句时,把每条指令用引号字符串分离,并写在
752	单独一行,在每个字符串结尾,除了 \n\t 结尾之外,在汇编输出中适当地缩进下
753	一条指令:
754	
755		asm ("magic %reg1, #42\n\t"
756		     "more_magic %reg2, %reg3"
757		     : /* outputs */ : /* inputs */ : /* clobbers */);
758	
759	
760			第二十章:条件编译
761	
762	只要可能,就不要在 .c 文件里面使用预处理条件;这样做让代码更难阅读并且逻辑难以
763	跟踪。替代方案是,在头文件定义函数在这些 .c 文件中使用这类的条件表达式,提供空
764	操作的桩版本(译注:桩程序,是指用来替换一部分功能的程序段)在 #else 情况下,
765	再从 .c 文件中无条件地调用这些函数。编译器会避免生成任何桩调用的代码,产生一致
766	的结果,但逻辑将更加清晰。
767	
768	宁可编译整个函数,而不是部分函数或部分表达式。而不是在一个表达式添加 ifdef,
769	解析部分或全部表达式到一个单独的辅助函数,并应用条件到该函数内。
770	
771	如果你有一个在特定配置中可能是未使用的函数或变量,编译器将警告它定义了但未使用,
772	标记这个定义为 __maybe_unused 而不是将它包含在一个预处理条件中。(然而,如果
773	一个函数或变量总是未使用的,就直接删除它。)
774	
775	在代码中,可能的情况下,使用 IS_ENABLED 宏来转化某个 Kconfig 标记为 C 的布尔
776	表达式,并在正常的 C 条件中使用它:
777	
778		if (IS_ENABLED(CONFIG_SOMETHING)) {
779			...
780		}
781	
782	编译器会无条件地做常数合并,就像使用 #ifdef 那样,包含或排除代码块,所以这不会
783	带来任何运行时开销。然而,这种方法依旧允许 C 编译器查看块内的代码,并检查它的正确
784	性(语法,类型,符号引用,等等)。因此,如果条件不满足,代码块内的引用符号将不存在,
785	你必须继续使用 #ifdef。
786	
787	在任何有意义的 #if 或 #ifdef 块的末尾(超过几行),在 #endif 同一行的后面写下
788	注释,指出该条件表达式被使用。例如:
789	
790		#ifdef CONFIG_SOMETHING
791		...
792		#endif /* CONFIG_SOMETHING */
793	
794	
795			附录 I:参考
796	
797	The C Programming Language, 第二版
798	作者:Brian W. Kernighan 和 Denni M. Ritchie.
799	Prentice Hall, Inc., 1988.
800	ISBN 0-13-110362-8 (软皮), 0-13-110370-9 (硬皮).
801	
802	The Practice of Programming
803	作者:Brian W. Kernighan 和 Rob Pike.
804	Addison-Wesley, Inc., 1999.
805	ISBN 0-201-61586-X.
806	
807	GNU 手册 - 遵循 K&R 标准和此文本 - cpp, gcc, gcc internals and indent,
808	都可以从 http://www.gnu.org/manual/ 找到
809	
810	WG14是C语言的国际标准化工作组,URL: http://www.open-std.org/JTC1/SC22/WG14/
811	
812	Kernel CodingStyle,作者 greg@kroah.com 发表于OLS 2002:
813	http://www.kroah.com/linux/talks/ols_2002_kernel_codingstyle_talk/html/
Hide Line Numbers


About Kernel Documentation Linux Kernel Contact Linux Resources Linux Blog