Linux 6.9-rc1
[linux-2.6-microblaze.git] / Documentation / translations / zh_CN / process / coding-style.rst
1 .. include:: ../disclaimer-zh_CN.rst
2
3 :Original: Documentation/process/coding-style.rst
4
5 .. _cn_codingstyle:
6
7 :译者:
8  - 张乐 Zhang Le <r0bertz@gentoo.org>
9  - Andy Deng <theandy.deng@gmail.com>
10  - 吴想成 <bobwxc@email.cn>
11
12 :校译:
13  - 王聪 Wang Cong <xiyou.wangcong@gmail.com>
14  - wheelz <kernel.zeng@gmail.com>
15  - 管旭东 Xudong Guan <xudong.guan@gmail.com>
16  - Li Zefan <lizf@cn.fujitsu.com>
17  - Wang Chen <wangchen@cn.fujitsu.com>
18
19 Linux 内核代码风格
20 ==================
21
22 这是一个简短的文档,描述了 linux 内核的首选代码风格。代码风格是因人而异的,
23 而且我不愿意把自己的观点强加给任何人,但这就像我去做任何事情都必须遵循的原则
24 那样,我也希望在绝大多数事上保持这种的态度。请 (在写代码时) 至少考虑一下这里
25 的代码风格。
26
27 首先,我建议你打印一份 GNU 代码规范,然后不要读。烧了它,这是一个具有重大象征
28 性意义的动作。
29
30 不管怎样,现在我们开始:
31
32
33 1) 缩进
34 -------
35
36 制表符是 8 个字符,所以缩进也是 8 个字符。有些异端运动试图将缩进变为 4 (甚至
37 2!) 字符深,这几乎相当于尝试将圆周率的值定义为 3。
38
39 理由:缩进的全部意义就在于清楚的定义一个控制块起止于何处。尤其是当你盯着你的
40 屏幕连续看了 20 小时之后,你将会发现大一点的缩进会使你更容易分辨缩进。
41
42 现在,有些人会抱怨 8 个字符的缩进会使代码向右边移动的太远,在 80 个字符的终端
43 屏幕上就很难读这样的代码。这个问题的答案是,如果你需要 3 级以上的缩进,不管用
44 何种方式你的代码已经有问题了,应该修正你的程序。
45
46 简而言之,8 个字符的缩进可以让代码更容易阅读,还有一个好处是当你的函数嵌套太
47 深的时候可以给你警告。留心这个警告。
48
49 在 switch 语句中消除多级缩进的首选的方式是让 ``switch`` 和从属于它的 ``case``
50 标签对齐于同一列,而不要 ``两次缩进`` ``case`` 标签。比如:
51
52 .. code-block:: c
53
54         switch (suffix) {
55         case 'G':
56         case 'g':
57                 mem <<= 30;
58                 break;
59         case 'M':
60         case 'm':
61                 mem <<= 20;
62                 break;
63         case 'K':
64         case 'k':
65                 mem <<= 10;
66                 fallthrough;
67         default:
68                 break;
69         }
70
71 不要把多个语句放在一行里,除非你有什么东西要隐藏:
72
73 .. code-block:: c
74
75         if (condition) do_this;
76           do_something_everytime;
77
78 不要使用逗号来避免使用大括号:
79
80 .. code-block:: c
81
82         if (condition)
83                 do_this(), do_that();
84
85 使用大括号包裹多语句:
86
87 .. code-block:: c
88
89         if (condition) {
90                 do_this();
91                 do_that();
92         }
93
94 也不要在一行里放多个赋值语句。内核代码风格超级简单。就是避免可能导致别人误读
95 的表达式。
96
97 除了注释、文档和 Kconfig 之外,不要使用空格来缩进,前面的例子是例外,是有意为
98 之。
99
100 选用一个好的编辑器,不要在行尾留空格。
101
102
103 2) 把长的行和字符串打散
104 -----------------------
105
106 代码风格的意义就在于使用平常使用的工具来维持代码的可读性和可维护性。
107
108 每一行的长度的限制是 80 列,我们强烈建议您遵守这个惯例。
109
110 长于 80 列的语句要打散成有意义的片段。除非超过 80 列能显著增加可读性,并且不
111 会隐藏信息。
112
113 子片段要明显短于母片段,并明显靠右。一种非常常用的样式是将子体与函数左括号对齐。
114
115 这同样适用于有着很长参数列表的函数头。
116
117 然而,绝对不要打散对用户可见的字符串,例如 printk 信息,因为这样就
118 很难对它们 grep。
119
120
121 3) 大括号和空格的放置
122 ---------------------
123
124 C 语言风格中另外一个常见问题是大括号的放置。和缩进大小不同,选择或弃用某种放
125 置策略并没有多少技术上的原因,不过首选的方式,就像 Kernighan 和 Ritchie 展示
126 给我们的,是把起始大括号放在行尾,而把结束大括号放在行首,所以:
127
128 .. code-block:: c
129
130         if (x is true) {
131                 we do y
132         }
133
134 这适用于所有的非函数语句块 (if, switch, for, while, do)。比如:
135
136 .. code-block:: c
137
138         switch (action) {
139         case KOBJ_ADD:
140                 return "add";
141         case KOBJ_REMOVE:
142                 return "remove";
143         case KOBJ_CHANGE:
144                 return "change";
145         default:
146                 return NULL;
147         }
148
149 不过,有一个例外,那就是函数:函数的起始大括号放置于下一行的开头,所以:
150
151 .. code-block:: c
152
153         int function(int x)
154         {
155                 body of function
156         }
157
158 全世界的异端可能会抱怨这个不一致性是……呃……不一致,不过所有思维健全的人
159 都知道 (a) K&R 是 **正确的** 并且 (b) K&R 是正确的。此外,不管怎样函数都是特
160 殊的 (C 函数是不能嵌套的)。
161
162 注意结束大括号独自占据一行,除非它后面跟着同一个语句的剩余部分,也就是 do 语
163 句中的 ``while`` 或者 if 语句中的 ``else`` ,像这样:
164
165 .. code-block:: c
166
167         do {
168                 body of do-loop
169         } while (condition);
170
171
172
173 .. code-block:: c
174
175         if (x == y) {
176                 ..
177         } else if (x > y) {
178                 ...
179         } else {
180                 ....
181         }
182
183 理由:K&R。
184
185 也请注意这种大括号的放置方式也能使空 (或者差不多空的) 行的数量最小化,同时不
186 失可读性。因此,由于你的屏幕上的新行是不可再生资源 (想想 25 行的终端屏幕),你
187 将会有更多的空行来放置注释。
188
189 当只有一个单独的语句的时候,不用加不必要的大括号。
190
191 .. code-block:: c
192
193         if (condition)
194                 action();
195
196
197
198 .. code-block:: c
199
200         if (condition)
201                 do_this();
202         else
203                 do_that();
204
205 这并不适用于只有一个条件分支是单语句的情况;这时所有分支都要使用大括号:
206
207 .. code-block:: c
208
209         if (condition) {
210                 do_this();
211                 do_that();
212         } else {
213                 otherwise();
214         }
215
216 3.1) 空格
217 *********
218
219 Linux 内核的空格使用方式 (主要) 取决于它是用于函数还是关键字。(大多数) 关键字
220 后要加一个空格。值得注意的例外是 sizeof, typeof, alignof 和 __attribute__,这
221 些关键字某些程度上看起来更像函数 (它们在 Linux 里也常常伴随小括号而使用,尽管
222 在 C 里这样的小括号不是必需的,就像 ``struct fileinfo info;`` 声明过后的
223 ``sizeof info``)。
224
225 所以在这些关键字之后放一个空格::
226
227         if, switch, case, for, do, while
228
229 但是不要在 sizeof, typeof, alignof 或者 __attribute__ 这些关键字之后放空格。
230 例如,
231
232 .. code-block:: c
233
234         s = sizeof(struct file);
235
236 不要在小括号里的表达式两侧加空格。这是一个 **反例** :
237
238 .. code-block:: c
239
240         s = sizeof( struct file );
241
242 当声明指针类型或者返回指针类型的函数时, ``*`` 的首选使用方式是使之靠近变量名
243 或者函数名,而不是靠近类型名。例子:
244
245 .. code-block:: c
246
247         char *linux_banner;
248         unsigned long long memparse(char *ptr, char **retptr);
249         char *match_strdup(substring_t *s);
250
251 在大多数二元和三元操作符两侧使用一个空格,例如下面所有这些操作符::
252
253         =  +  -  <  >  *  /  %  |  &  ^  <=  >=  ==  !=  ?  :
254
255 但是一元操作符后不要加空格::
256
257         &  *  +  -  ~  !  sizeof  typeof  alignof  __attribute__  defined
258
259 后缀自加和自减一元操作符前不加空格::
260
261         ++  --
262
263 前缀自加和自减一元操作符后不加空格::
264
265         ++  --
266
267 ``.`` 和 ``->`` 结构体成员操作符前后不加空格。
268
269 不要在行尾留空白。有些可以自动缩进的编辑器会在新行的行首加入适量的空白,然后
270 你就可以直接在那一行输入代码。不过假如你最后没有在那一行输入代码,有些编辑器
271 就不会移除已经加入的空白,就像你故意留下一个只有空白的行。包含行尾空白的行就
272 这样产生了。
273
274 当 git 发现补丁包含了行尾空白的时候会警告你,并且可以应你的要求去掉行尾空白;
275 不过如果你是正在打一系列补丁,这样做会导致后面的补丁失败,因为你改变了补丁的
276 上下文。
277
278
279 4) 命名
280 -------
281
282 C 是一个简朴的语言,你的命名也应该这样。和 Modula-2 和 Pascal 程序员不同,
283 C 程序员不使用类似 ThisVariableIsATemporaryCounter 这样华丽的名字。C 程序员会
284 称那个变量为 ``tmp`` ,这样写起来会更容易,而且至少不会令其难于理解。
285
286 不过,虽然混用大小写的名字是不提倡使用的,但是全局变量还是需要一个具描述性的
287 名字。称一个全局函数为 ``foo`` 是一个难以饶恕的错误。
288
289 全局变量 (只有当你 **真正** 需要它们的时候再用它) 需要有一个具描述性的名字,就
290 像全局函数。如果你有一个可以计算活动用户数量的函数,你应该叫它
291 ``count_active_users()`` 或者类似的名字,你不应该叫它 ``cntuser()`` 。
292
293 在函数名中包含函数类型 (所谓的匈牙利命名法) 是脑子出了问题——编译器知道那些类
294 型而且能够检查那些类型,这样做只能把程序员弄糊涂了。
295
296 本地变量名应该简短,而且能够表达相关的含义。如果你有一些随机的整数型的循环计
297 数器,它应该被称为 ``i`` 。叫它 ``loop_counter`` 并无益处,如果它没有被误解的
298 可能的话。类似的, ``tmp`` 可以用来称呼任意类型的临时变量。
299
300 如果你怕混淆了你的本地变量名,你就遇到另一个问题了,叫做函数增长荷尔蒙失衡综
301 合征。请看第六章 (函数)。
302
303 对于符号名称和文档,避免引入新的“master/slave”(或独立于“master”的“slave”)
304 和“blacklist/whitelist”。
305
306 “master/slave”推荐替换为:
307     '{primary,main} / {secondary,replica,subordinate}'
308     '{initiator,requester} / {target,responder}'
309     '{controller,host} / {device,worker,proxy}'
310     'leader/follower'
311     'director/performer'
312
313 “blacklist/whitelist”推荐替换为:
314     'denylist/allowlist'
315     'blocklist/passlist'
316
317 引入新用法的例外情况是:维护用户空间ABI/API,或更新现有(截至2020年)硬件或
318 协议规范的代码时要求这些术语。对于新规范,尽可能将术语的规范用法转换为内核
319 编码标准。
320
321 .. warning::
322         以上主从、黑白名单规则不适用于中文文档,请勿更改中文术语!
323
324 5) Typedef
325 ----------
326
327 不要使用类似 ``vps_t`` 之类的东西。
328
329 对结构体和指针使用 typedef 是一个 **错误** 。当你在代码里看到:
330
331 .. code-block:: c
332
333         vps_t a;
334
335 这代表什么意思呢?
336
337 相反,如果是这样
338
339 .. code-block:: c
340
341         struct virtual_container *a;
342
343 你就知道 ``a`` 是什么了。
344
345 很多人认为 typedef ``能提高可读性`` 。实际不是这样的。它们只在下列情况下有用:
346
347  (a) 完全不透明的对象 (这种情况下要主动使用 typedef 来 **隐藏** 这个对象实际上
348      是什么)。
349
350      例如: ``pte_t`` 等不透明对象,你只能用合适的访问函数来访问它们。
351
352      .. note::
353
354        不透明性和“访问函数”本身是不好的。我们使用 pte_t 等类型的原因在于真
355        的是完全没有任何共用的可访问信息。
356
357  (b) 清楚的整数类型,如此,这层抽象就可以 **帮助** 消除到底是 ``int`` 还是
358      ``long`` 的混淆。
359
360      u8/u16/u32 是完全没有问题的 typedef,不过它们更符合类别 (d) 而不是这里。
361
362      .. note::
363
364        要这样做,必须事出有因。如果某个变量是 ``unsigned long`` ,那么没有必要
365
366         typedef unsigned long myflags_t;
367
368      不过如果有一个明确的原因,比如它在某种情况下可能会是一个 ``unsigned int``
369      而在其他情况下可能为 ``unsigned long`` ,那么就不要犹豫,请务必使用
370      typedef。
371
372  (c) 当你使用 sparse 按字面的创建一个 **新** 类型来做类型检查的时候。
373
374  (d) 和标准 C99 类型相同的类型,在某些例外的情况下。
375
376      虽然让眼睛和脑筋来适应新的标准类型比如 ``uint32_t`` 不需要花很多时间,可
377      是有些人仍然拒绝使用它们。
378
379      因此,Linux 特有的等同于标准类型的 ``u8/u16/u32/u64`` 类型和它们的有符号
380      类型是被允许的——尽管在你自己的新代码中,它们不是强制要求要使用的。
381
382      当编辑已经使用了某个类型集的已有代码时,你应该遵循那些代码中已经做出的选
383      择。
384
385  (e) 可以在用户空间安全使用的类型。
386
387      在某些用户空间可见的结构体里,我们不能要求 C99 类型而且不能用上面提到的
388      ``u32`` 类型。因此,我们在与用户空间共享的所有结构体中使用 __u32 和类似
389      的类型。
390
391 可能还有其他的情况,不过基本的规则是 **永远不要** 使用 typedef,除非你可以明
392 确的应用上述某个规则中的一个。
393
394 总的来说,如果一个指针或者一个结构体里的元素可以合理的被直接访问到,那么它们
395 就不应该是一个 typedef。
396
397
398 6) 函数
399 -------
400
401 函数应该简短而漂亮,并且只完成一件事情。函数应该可以一屏或者两屏显示完 (我们
402 都知道 ISO/ANSI 屏幕大小是 80x24),只做一件事情,而且把它做好。
403
404 一个函数的最大长度是和该函数的复杂度和缩进级数成反比的。所以,如果你有一个理
405 论上很简单的只有一个很长 (但是简单) 的 case 语句的函数,而且你需要在每个 case
406 里做很多很小的事情,这样的函数尽管很长,但也是可以的。
407
408 不过,如果你有一个复杂的函数,而且你怀疑一个天分不是很高的高中一年级学生可能
409 甚至搞不清楚这个函数的目的,你应该严格遵守前面提到的长度限制。使用辅助函数,
410 并为之取个具描述性的名字 (如果你觉得它们的性能很重要的话,可以让编译器内联它
411 们,这样的效果往往会比你写一个复杂函数的效果要好。)
412
413 函数的另外一个衡量标准是本地变量的数量。此数量不应超过 5-10 个,否则你的函数
414 就有问题了。重新考虑一下你的函数,把它分拆成更小的函数。人的大脑一般可以轻松
415 的同时跟踪 7 个不同的事物,如果再增多的话,就会糊涂了。即便你聪颖过人,你也可
416 能会记不清你 2 个星期前做过的事情。
417
418 在源文件里,使用空行隔开不同的函数。如果该函数需要被导出,它的 **EXPORT** 宏
419 应该紧贴在它的结束大括号之下。比如:
420
421 .. code-block:: c
422
423         int system_is_up(void)
424         {
425                 return system_state == SYSTEM_RUNNING;
426         }
427         EXPORT_SYMBOL(system_is_up);
428
429 6.1) 函数原型
430 *************
431
432 在函数原型中包含参数名和它们的数据类型。虽然 C 语言里没有这样的要求,但在
433 Linux 里这是提倡的做法,因为这样可以很简单的给读者提供更多的有价值的信息。
434
435 不要在函数声明里使用 ``extern`` 关键字,因为这会导致代码行变长,并且不是严格
436 必需的。
437
438 写函数原型时,请保持 `元素顺序规则 <https://lore.kernel.org/mm-commits/CAHk-=wiOCLRny5aifWNhr621kYrJwhfURsa0vFPeUEm8mF0ufg@mail.gmail.com/>`_ 。
439 例如下列函数声明::
440
441  __init void * __must_check action(enum magic value, size_t size, u8 count,
442                                    char *fmt, ...) __printf(4, 5) __malloc;
443
444 推荐的函数原型元素顺序是:
445
446 - 储存类型(下方的 ``static __always_inline`` ,注意 ``__always_inline``
447   技术上来讲是个属性但被当做 ``inline`` )
448 - 储存类型属性(上方的 ``__init`` ——即节声明,但也像 ``__cold`` )
449 - 返回类型(上方的 ``void *`` )
450 - 返回类型属性(上方的 ``__must_check`` )
451 - 函数名(上方的 ``action`` )
452 - 函数参数(上方的 ``(enum magic value, size_t size, u8 count, char *fmt, ...)`` ,
453   注意必须写上参数名)
454 - 函数参数属性(上方的 ``__printf(4, 5)`` )
455 - 函数行为属性(上方的 ``__malloc`` )
456
457 请注意,对于函数 **定义** (即实际函数体),编译器不允许在函数参数之后添加函
458 数参数属性。在这种情况下,它们应该跟随存储类型属性(例如,与上面的 **声明**
459 示例相比,请注意下面的 ``__printf(4, 5)`` 的位置发生了变化)::
460
461  static __always_inline __init __printf(4, 5) void * __must_check action(enum magic value,
462                 size_t size, u8 count, char *fmt, ...) __malloc
463  {
464         ...
465  }
466
467 7) 集中的函数退出途径
468 ---------------------
469
470 虽然被某些人声称已经过时,但是 goto 语句的等价物还是经常被编译器所使用,具体
471 形式是无条件跳转指令。
472
473 当一个函数从多个位置退出,并且需要做一些类似清理的常见操作时,goto 语句就很方
474 便了。如果并不需要清理操作,那么直接 return 即可。
475
476 选择一个能够说明 goto 行为或它为何存在的标签名。如果 goto 要释放 ``buffer``,
477 一个不错的名字可以是 ``out_free_buffer:`` 。别去使用像 ``err1:`` 和 ``err2:``
478 这样的GW_BASIC 名称,因为一旦你添加或删除了 (函数的) 退出路径,你就必须对它们
479 重新编号,这样会难以去检验正确性。
480
481 使用 goto 的理由是:
482
483 - 无条件语句容易理解和跟踪
484 - 嵌套程度减小
485 - 可以避免由于修改时忘记更新个别的退出点而导致错误
486 - 让编译器省去删除冗余代码的工作 ;)
487
488 .. code-block:: c
489
490         int fun(int a)
491         {
492                 int result = 0;
493                 char *buffer;
494
495                 buffer = kmalloc(SIZE, GFP_KERNEL);
496                 if (!buffer)
497                         return -ENOMEM;
498
499                 if (condition1) {
500                         while (loop1) {
501                                 ...
502                         }
503                         result = 1;
504                         goto out_free_buffer;
505                 }
506                 ...
507         out_free_buffer:
508                 kfree(buffer);
509                 return result;
510         }
511
512 一个需要注意的常见错误是 ``单 err 错误`` ,就像这样:
513
514 .. code-block:: c
515
516         err:
517                 kfree(foo->bar);
518                 kfree(foo);
519                 return ret;
520
521 这段代码的错误是,在某些退出路径上 ``foo`` 是 NULL。通常情况下,通过把它分离
522 成两个错误标签 ``err_free_bar:`` 和 ``err_free_foo:`` 来修复这个错误:
523
524 .. code-block:: c
525
526         err_free_bar:
527                 kfree(foo->bar);
528         err_free_foo:
529                 kfree(foo);
530                 return ret;
531
532 理想情况下,你应该模拟错误来测试所有退出路径。
533
534
535 8) 注释
536 -------
537
538 注释是好的,不过有过度注释的危险。永远不要在注释里解释你的代码是如何运作的:
539 更好的做法是让别人一看你的代码就可以明白,解释写的很差的代码是浪费时间。
540
541 一般来说你用注释告诉别人你的代码做了什么,而不是怎么做的。也请你不要把
542 注释放在一个函数体内部:如果函数复杂到你需要独立的注释其中的一部分,你很可能
543 需要回到第六章看一看。你可以做一些小注释来注明或警告某些很聪明 (或者槽糕) 的
544 做法,但不要加太多。你应该做的,是把注释放在函数的头部,告诉人们它做了什么,
545 也可以加上它做这些事情的原因。
546
547 当注释内核 API 函数时,请使用 kernel-doc 格式。详见
548 Documentation/translations/zh_CN/doc-guide/index.rst 和 scripts/kernel-doc 。
549
550 长 (多行) 注释的首选风格是:
551
552 .. code-block:: c
553
554         /*
555          * This is the preferred style for multi-line
556          * comments in the Linux kernel source code.
557          * Please use it consistently.
558          *
559          * Description:  A column of asterisks on the left side,
560          * with beginning and ending almost-blank lines.
561          */
562
563 对于在 net/ 和 drivers/net/ 的文件,首选的长 (多行) 注释风格有些不同。
564
565 .. code-block:: c
566
567         /* The preferred comment style for files in net/ and drivers/net
568          * looks like this.
569          *
570          * It is nearly the same as the generally preferred comment style,
571          * but there is no initial almost-blank line.
572          */
573
574 注释数据也是很重要的,不管是基本类型还是衍生类型。为了方便实现这一点,每一行
575 应只声明一个数据 (不要使用逗号来一次声明多个数据)。这样你就有空间来为每个数据
576 写一段小注释来解释它们的用途了。
577
578
579 9) 你已经把事情弄糟了
580 ---------------------
581
582 这没什么,我们都是这样。可能你长期使用 Unix 的朋友已经告诉你
583 ``GNU emacs`` 能自动帮你格式化 C 源代码,而且你也注意到了,确实是这样,不过它
584 所使用的默认值和我们想要的相去甚远 (实际上,甚至比随机打的还要差——无数个猴子
585 在 GNU emacs 里打字永远不会创造出一个好程序)
586 *(译注:Infinite Monkey Theorem)*
587
588 所以你要么放弃 GNU emacs,要么改变它让它使用更合理的设定。要采用后一个方案,
589 你可以把下面这段粘贴到你的 .emacs 文件里。
590
591 .. code-block:: elisp
592
593   (defun c-lineup-arglist-tabs-only (ignored)
594     "Line up argument lists by tabs, not spaces"
595     (let* ((anchor (c-langelem-pos c-syntactic-element))
596            (column (c-langelem-2nd-pos c-syntactic-element))
597            (offset (- (1+ column) anchor))
598            (steps (floor offset c-basic-offset)))
599       (* (max steps 1)
600          c-basic-offset)))
601
602   (dir-locals-set-class-variables
603    'linux-kernel
604    '((c-mode . (
605           (c-basic-offset . 8)
606           (c-label-minimum-indentation . 0)
607           (c-offsets-alist . (
608                   (arglist-close         . c-lineup-arglist-tabs-only)
609                   (arglist-cont-nonempty .
610                       (c-lineup-gcc-asm-reg c-lineup-arglist-tabs-only))
611                   (arglist-intro         . +)
612                   (brace-list-intro      . +)
613                   (c                     . c-lineup-C-comments)
614                   (case-label            . 0)
615                   (comment-intro         . c-lineup-comment)
616                   (cpp-define-intro      . +)
617                   (cpp-macro             . -1000)
618                   (cpp-macro-cont        . +)
619                   (defun-block-intro     . +)
620                   (else-clause           . 0)
621                   (func-decl-cont        . +)
622                   (inclass               . +)
623                   (inher-cont            . c-lineup-multi-inher)
624                   (knr-argdecl-intro     . 0)
625                   (label                 . -1000)
626                   (statement             . 0)
627                   (statement-block-intro . +)
628                   (statement-case-intro  . +)
629                   (statement-cont        . +)
630                   (substatement          . +)
631                   ))
632           (indent-tabs-mode . t)
633           (show-trailing-whitespace . t)
634           ))))
635
636   (dir-locals-set-directory-class
637    (expand-file-name "~/src/linux-trees")
638    'linux-kernel)
639
640 这会让 emacs 在 ``~/src/linux-trees`` 下的 C 源文件获得更好的内核代码风格。
641
642 不过就算你尝试让 emacs 正确的格式化代码失败了,也并不意味着你失去了一切:还可
643 以用 ``indent`` 。
644
645 不过,GNU indent 也有和 GNU emacs 一样有问题的设定,所以你需要给它一些命令选
646 项。不过,这还不算太糟糕,因为就算是 GNU indent 的作者也认同 K&R 的权威性
647 (GNU 的人并不是坏人,他们只是在这个问题上被严重的误导了),所以你只要给 indent
648 指定选项 ``-kr -i8`` (代表 ``K&R,8 字符缩进``),或使用 ``scripts/Lindent``
649 这样就可以以最时髦的方式缩进源代码。
650
651 ``indent`` 有很多选项,特别是重新格式化注释的时候,你可能需要看一下它的手册。
652 不过记住: ``indent`` 不能修正坏的编程习惯。
653
654 请注意,您还可以使用 ``clang-format`` 工具帮助您处理这些规则,快速自动重新格
655 式化部分代码,并审阅整个文件以发现代码风格错误、打字错误和可能的改进。它还可
656 以方便地排序 ``#include`` ,对齐变量/宏,重排文本和其他类似任务。
657 详见 Documentation/process/clang-format.rst 。
658
659
660 10) Kconfig 配置文件
661 --------------------
662
663 对于遍布源码树的所有 Kconfig* 配置文件来说,它们缩进方式有所不同。紧挨着
664 ``config`` 定义的行,用一个制表符缩进,然而 help 信息的缩进则额外增加 2 个空
665 格。举个例子::
666
667   config AUDIT
668         bool "Auditing support"
669         depends on NET
670         help
671           Enable auditing infrastructure that can be used with another
672           kernel subsystem, such as SELinux (which requires this for
673           logging of avc messages output).  Does not do system-call
674           auditing without CONFIG_AUDITSYSCALL.
675
676 而那些危险的功能 (比如某些文件系统的写支持) 应该在它们的提示字符串里显著的声
677 明这一点::
678
679   config ADFS_FS_RW
680         bool "ADFS write support (DANGEROUS)"
681         depends on ADFS_FS
682         ...
683
684 要查看配置文件的完整文档,请看 Documentation/kbuild/kconfig-language.rst 。
685
686
687 11) 数据结构
688 ------------
689
690 如果一个数据结构,在创建和销毁它的单线执行环境之外可见,那么它必须要有一个引
691 用计数器。内核里没有垃圾收集 (并且内核之外的垃圾收集慢且效率低下),这意味着你
692 绝对需要记录你对这种数据结构的使用情况。
693
694 引用计数意味着你能够避免上锁,并且允许多个用户并行访问这个数据结构——而不需要
695 担心这个数据结构仅仅因为暂时不被使用就消失了,那些用户可能不过是沉睡了一阵或
696 者做了一些其他事情而已。
697
698 注意上锁 **不能** 取代引用计数。上锁是为了保持数据结构的一致性,而引用计数是一
699 个内存管理技巧。通常二者都需要,不要把两个搞混了。
700
701 很多数据结构实际上有 2 级引用计数,它们通常有不同 ``类`` 的用户。子类计数器统
702 计子类用户的数量,每当子类计数器减至零时,全局计数器减一。
703
704 这种 ``多级引用计数`` 的例子可以在内存管理 (``struct mm_struct``: mm_users 和
705 mm_count),和文件系统 (``struct super_block``: s_count 和 s_active) 中找到。
706
707 记住:如果另一个执行线索可以找到你的数据结构,但这个数据结构没有引用计数器,
708 这里几乎肯定是一个 bug。
709
710
711 12) 宏,枚举和RTL
712 -----------------
713
714 用于定义常量的宏的名字及枚举里的标签需要大写。
715
716 .. code-block:: c
717
718         #define CONSTANT 0x12345
719
720 在定义几个相关的常量时,最好用枚举。
721
722 宏的名字请用大写字母,不过形如函数的宏的名字可以用小写字母。
723
724 通常如果能写成内联函数就不要写成像函数的宏。
725
726 含有多个语句的宏应该被包含在一个 do-while 代码块里:
727
728 .. code-block:: c
729
730         #define macrofun(a, b, c)                       \
731                 do {                                    \
732                         if (a == 5)                     \
733                                 do_this(b, c);          \
734                 } while (0)
735
736 使用宏的时候应避免的事情:
737
738 1) 影响控制流程的宏:
739
740 .. code-block:: c
741
742         #define FOO(x)                                  \
743                 do {                                    \
744                         if (blah(x) < 0)                \
745                                 return -EBUGGERED;      \
746                 } while (0)
747
748 **非常** 不好。它看起来像一个函数,不过却能导致 ``调用`` 它的函数退出;不要打
749 乱读者大脑里的语法分析器。
750
751 2) 依赖于一个固定名字的本地变量的宏:
752
753 .. code-block:: c
754
755         #define FOO(val) bar(index, val)
756
757 可能看起来像是个不错的东西,不过它非常容易把读代码的人搞糊涂,而且容易导致看起
758 来不相关的改动带来错误。
759
760 3) 作为左值的带参数的宏: FOO(x) = y;如果有人把 FOO 变成一个内联函数的话,这
761    种用法就会出错了。
762
763 4) 忘记了优先级:使用表达式定义常量的宏必须将表达式置于一对小括号之内。带参数
764    的宏也要注意此类问题。
765
766 .. code-block:: c
767
768         #define CONSTANT 0x4000
769         #define CONSTEXP (CONSTANT | 3)
770
771 5) 在宏里定义类似函数的本地变量时命名冲突:
772
773 .. code-block:: c
774
775         #define FOO(x)                          \
776         ({                                      \
777                 typeof(x) ret;                  \
778                 ret = calc_ret(x);              \
779                 (ret);                          \
780         })
781
782 ret 是本地变量的通用名字—— __foo_ret 更不容易与一个已存在的变量冲突。
783
784 cpp 手册对宏的讲解很详细。gcc internals 手册也详细讲解了 RTL,内核里的汇编语
785 言经常用到它。
786
787
788 13) 打印内核消息
789 ----------------
790
791 内核开发者应该看起来有文化。请一定注意内核信息的拼写,以给人良好的印象。
792 不要用不规范的单词比如 ``dont``,而要用 ``do not`` 或者 ``don't`` 。保证这些信
793 息简单明了、无歧义。
794
795 内核信息不必以英文句号结束。
796
797 在小括号里打印数字 (%d) 没有任何价值,应该避免这样做。
798
799 <linux/device.h> 里有一些驱动模型诊断宏,你应该使用它们,以确保信息对应于正确
800 的设备和驱动,并且被标记了正确的消息级别。这些宏有:dev_err(), dev_warn(),
801 dev_info() 等等。对于那些不和某个特定设备相关连的信息,<linux/printk.h> 定义
802 了 pr_notice(), pr_info(), pr_warn(), pr_err() 和其他。
803
804 写出好的调试信息可以是一个很大的挑战;一旦你写出后,这些信息在远程除错时能提
805 供极大的帮助。然而打印调试信息的处理方式同打印非调试信息不同。其他 pr_XXX()
806 函数能无条件地打印,pr_debug() 却不;默认情况下它不会被编译,除非定义了 DEBUG
807 或设定了 CONFIG_DYNAMIC_DEBUG。实际这同样是为了 dev_dbg(),一个相关约定是在一
808 个已经开启了 DEBUG 时,使用 VERBOSE_DEBUG 来添加 dev_vdbg()。
809
810 许多子系统拥有 Kconfig 调试选项来开启对应 Makefile 里面的 -DDEBUG;在其他
811 情况下,特殊文件使用 #define DEBUG。当一条调试信息需要被无条件打印时,例如,
812 如果已经包含一个调试相关的 #ifdef 条件,printk(KERN_DEBUG ...) 就可被使用。
813
814
815 14) 分配内存
816 ------------
817
818 内核提供了下面的一般用途的内存分配函数:
819 kmalloc(), kzalloc(), kmalloc_array(), kcalloc(), vmalloc() 和 vzalloc()。
820 请参考 API 文档以获取有关它们的详细信息:
821 Documentation/translations/zh_CN/core-api/memory-allocation.rst 。
822
823 传递结构体大小的首选形式是这样的:
824
825 .. code-block:: c
826
827         p = kmalloc(sizeof(*p), ...);
828
829 另外一种传递方式中,sizeof 的操作数是结构体的名字,这样会降低可读性,并且可能
830 会引入 bug。有可能指针变量类型被改变时,而对应的传递给内存分配函数的 sizeof
831 的结果不变。
832
833 强制转换一个 void 指针返回值是多余的。C 语言本身保证了从 void 指针到其他任何
834 指针类型的转换是没有问题的。
835
836 分配一个数组的首选形式是这样的:
837
838 .. code-block:: c
839
840         p = kmalloc_array(n, sizeof(...), ...);
841
842 分配一个零长数组的首选形式是这样的:
843
844 .. code-block:: c
845
846         p = kcalloc(n, sizeof(...), ...);
847
848 两种形式都会检查分配 n * sizeof(...) 大小时内存的溢出,如果溢出返回 NULL。
849
850 在没有 __GFP_NOWARN 的情况下使用时,这些通用分配函数都会在失败时发起堆栈转储,
851 因此当返回NULL时,没有必要发出额外的失败消息。
852
853 15) 内联弊病
854 ------------
855
856 有一个常见的误解是 ``内联`` 是 gcc 提供的可以让代码运行更快的一个选项。虽然使
857 用内联函数有时候是恰当的 (比如作为一种替代宏的方式,请看第十二章),不过很多情
858 况下不是这样。inline 的过度使用会使内核变大,从而使整个系统运行速度变慢。
859 因为体积大内核会占用更多的指令高速缓存,而且会导致 pagecache 的可用内存减少。
860 想象一下,一次 pagecache 未命中就会导致一次磁盘寻址,将耗时 5 毫秒。5 毫秒的
861 时间内 CPU 能执行很多很多指令。
862
863 一个基本的原则是如果一个函数有 3 行以上,就不要把它变成内联函数。这个原则的一
864 个例外是,如果你知道某个参数是一个编译时常量,而且因为这个常量你确定编译器在
865 编译时能优化掉你的函数的大部分代码,那仍然可以给它加上 inline 关键字。
866 kmalloc() 内联函数就是一个很好的例子。
867
868 人们经常主张给 static 的而且只用了一次的函数加上 inline,如此不会有任何损失,
869 因为没有什么好权衡的。虽然从技术上说这是正确的,但是实际上这种情况下即使不加
870 inline gcc 也可以自动使其内联。而且其他用户可能会要求移除 inline,由此而来的
871 争论会抵消 inline 自身的潜在价值,得不偿失。
872
873
874 16) 函数返回值及命名
875 --------------------
876
877 函数可以返回多种不同类型的值,最常见的一种是表明函数执行成功或者失败的值。这样
878 的一个值可以表示为一个错误代码整数 (-Exxx=失败,0=成功) 或者一个 ``成功``
879 布尔值 (0=失败,非0=成功)。
880
881 混合使用这两种表达方式是难于发现的 bug 的来源。如果 C 语言本身严格区分整形和
882 布尔型变量,那么编译器就能够帮我们发现这些错误... 不过 C 语言不区分。为了避免
883 产生这种 bug,请遵循下面的惯例::
884
885         如果函数的名字是一个动作或者强制性的命令,那么这个函数应该返回错误代
886         码整数。如果是一个判断,那么函数应该返回一个“成功”布尔值。
887
888 比如, ``add work`` 是一个命令,所以 add_work() 在成功时返回 0,在失败时返回
889 -EBUSY。类似的,因为 ``PCI device present`` 是一个判断,所以 pci_dev_present()
890 在成功找到一个匹配的设备时应该返回 1,如果找不到时应该返回 0。
891
892 所有 EXPORTed 函数都必须遵守这个惯例,所有的公共函数也都应该如此。私有
893 (static) 函数不需要如此,但是我们也推荐这样做。
894
895 返回值是实际计算结果而不是计算是否成功的标志的函数不受此惯例的限制。通常
896 他们通过返回一些正常值范围之外的结果来表示出错。典型的例子是返回指针的函数,
897 他们使用 NULL 或者 ERR_PTR 机制来报告错误。
898
899 17) 使用布尔类型
900 ----------------
901
902 Linux内核布尔(bool)类型是C99 _Bool类型的别名。布尔值只能为0或1,而对布尔的
903 隐式或显式转换将自动将值转换为true或false。在使用布尔类型时 **不需要** 构造,
904 它会消除一类错误。
905
906 使用布尔值时,应使用true和false定义,而不是1和0。
907
908 布尔函数返回类型和堆栈变量总是可以在适当的时候使用。鼓励使用布尔来提高可读性,
909 并且布尔值在存储时通常比“int”更好。
910
911 如果缓存行布局或值的大小很重要,请不要使用布尔,因为其大小和对齐方式根据编译
912 的体系结构而不同。针对对齐和大小进行优化的结构体不应使用布尔。
913
914 如果一个结构体有多个true/false值,请考虑将它们合并为具有1比特成员的位域,或使
915 用适当的固定宽度类型,如u8。
916
917 类似地,对于函数参数,多个true/false值可以合并为单个按位的“标志”参数,如果调
918 用点具有裸true/false常量,“标志”参数通常是更具可读性的替代方法。
919
920 总之,在结构体和参数中有限地使用布尔可以提高可读性。
921
922 18) 不要重新发明内核宏
923 ----------------------
924
925 头文件 include/linux/kernel.h 包含了一些宏,你应该使用它们,而不要自己写一些
926 它们的变种。比如,如果你需要计算一个数组的长度,使用这个宏
927
928 .. code-block:: c
929
930         #define ARRAY_SIZE(x) (sizeof(x) / sizeof((x)[0]))
931
932 类似的,如果你要计算某结构体成员的大小,使用
933
934 .. code-block:: c
935
936         #define sizeof_field(t, f) (sizeof(((t*)0)->f))
937
938 还有可以做严格的类型检查的 min() 和 max() 宏,如果你需要可以使用它们。你可以
939 自己看看那个头文件里还定义了什么你可以拿来用的东西,如果有定义的话,你就不应
940 在你的代码里自己重新定义。
941
942
943 19) 编辑器模式行和其他需要罗嗦的事情
944 ------------------------------------
945
946 有一些编辑器可以解释嵌入在源文件里的由一些特殊标记标明的配置信息。比如,emacs
947 能够解析被标记成这样的行:
948
949 .. code-block:: c
950
951         -*- mode: c -*-
952
953 或者这样的:
954
955 .. code-block:: c
956
957         /*
958         Local Variables:
959         compile-command: "gcc -DMAGIC_DEBUG_FLAG foo.c"
960         End:
961         */
962
963 Vim 能够解析这样的标记:
964
965 .. code-block:: c
966
967         /* vim:set sw=8 noet */
968
969 不要在源代码中包含任何这样的内容。每个人都有他自己的编辑器配置,你的源文件不
970 应该覆盖别人的配置。这包括有关缩进和模式配置的标记。人们可以使用他们自己定制
971 的模式,或者使用其他可以产生正确的缩进的巧妙方法。
972
973
974 20) 内联汇编
975 ------------
976
977 在特定架构的代码中,你可能需要内联汇编与 CPU 和平台相关功能连接。需要这么做时
978 就不要犹豫。然而,当 C 可以完成工作时,不要平白无故地使用内联汇编。在可能的情
979 况下,你可以并且应该用 C 和硬件沟通。
980
981 请考虑去写捆绑通用位元 (wrap common bits) 的内联汇编的简单辅助函数,别去重复
982 地写下只有细微差异内联汇编。记住内联汇编可以使用 C 参数。
983
984 大型,有一定复杂度的汇编函数应该放在 .S 文件内,用相应的 C 原型定义在 C 头文
985 件中。汇编函数的 C 原型应该使用 ``asmlinkage`` 。
986
987 你可能需要把汇编语句标记为 volatile,用来阻止 GCC 在没发现任何副作用后就把它
988 移除了。你不必总是这样做,尽管,这不必要的举动会限制优化。
989
990 在写一个包含多条指令的单个内联汇编语句时,把每条指令用引号分割而且各占一行,
991 除了最后一条指令外,在每个指令结尾加上 ``\n\t`` ,让汇编输出时可以正确地缩进
992 下一条指令:
993
994 .. code-block:: c
995
996         asm ("magic %reg1, #42\n\t"
997              "more_magic %reg2, %reg3"
998              : /* outputs */ : /* inputs */ : /* clobbers */);
999
1000
1001 21) 条件编译
1002 ------------
1003
1004 只要可能,就不要在 .c 文件里面使用预处理条件 (#if, #ifdef);这样做会让代码更难
1005 阅读并且更难去跟踪逻辑。替代方案是,在头文件中用预处理条件提供给那些 .c 文件
1006 使用,再给 #else 提供一个空桩 (no-op stub) 版本,然后在 .c 文件内无条件地调用
1007 那些 (定义在头文件内的) 函数。这样做,编译器会避免为桩函数 (stub) 的调用生成
1008 任何代码,产生的结果是相同的,但逻辑将更加清晰。
1009
1010 最好倾向于编译整个函数,而不是函数的一部分或表达式的一部分。与其放一个 ifdef
1011 在表达式内,不如分解出部分或全部表达式,放进一个单独的辅助函数,并应用预处理
1012 条件到这个辅助函数内。
1013
1014 如果你有一个在特定配置中,可能变成未使用的函数或变量,编译器会警告它定义了但
1015 未使用,请把它标记为 __maybe_unused 而不是将它包含在一个预处理条件中。(然而,
1016 如果一个函数或变量总是未使用,就直接删除它。)
1017
1018 在代码中,尽可能地使用 IS_ENABLED 宏来转化某个 Kconfig 标记为 C 的布尔
1019 表达式,并在一般的 C 条件中使用它:
1020
1021 .. code-block:: c
1022
1023         if (IS_ENABLED(CONFIG_SOMETHING)) {
1024                 ...
1025         }
1026
1027 编译器会做常量折叠,然后就像使用 #ifdef 那样去包含或排除代码块,所以这不会带
1028 来任何运行时开销。然而,这种方法依旧允许 C 编译器查看块内的代码,并检查它的正
1029 确性 (语法,类型,符号引用,等等)。因此,如果条件不满足,代码块内的引用符号就
1030 不存在时,你还是必须去用 #ifdef。
1031
1032 在任何有意义的 #if 或 #ifdef 块的末尾 (超过几行的),在 #endif 同一行的后面写下
1033 注解,注释这个条件表达式。例如:
1034
1035 .. code-block:: c
1036
1037         #ifdef CONFIG_SOMETHING
1038         ...
1039         #endif /* CONFIG_SOMETHING */
1040
1041
1042 附录 I) 参考资料
1043 ----------------
1044
1045 The C Programming Language, 2nd Edition
1046 作者:Brian W. Kernighan 和 Denni M. Ritchie.
1047 Prentice Hall, Inc., 1988.
1048 ISBN 0-13-110362-8 (平装), 0-13-110370-9 (精装).
1049
1050 .. note::
1051
1052     《C程序设计语言(第2版)》
1053     作者:[美] Brian W. Kernighan / [美] Dennis M. Ritchie
1054     译者:徐宝文 / 李志 / 尤晋元(审校)
1055     出版社:机械工业出版社,2019
1056     ISBN:9787111617945
1057
1058 The Practice of Programming
1059 作者:Brian W. Kernighan 和 Rob Pike.
1060 Addison-Wesley, Inc., 1999.
1061 ISBN 0-201-61586-X.
1062
1063 .. note::
1064
1065     《程序设计实践》
1066     作者:[美] Brian W. Kernighan / [美] Rob Pike
1067     出版社:机械工业出版社,2005
1068     ISBN:9787111091578
1069
1070     《程序设计实践》
1071     作者:[美] Brian W. Kernighan / Rob Pike
1072     译者:裘宗燕
1073     出版社:机械工业出版社,2000
1074     ISBN:9787111075738
1075
1076 GNU 手册 - 遵循 K&R 标准和此文本 - cpp, gcc, gcc internals and indent,
1077 都可以从 https://www.gnu.org/manual/ 找到
1078
1079 WG14 是 C 语言的国际标准化工作组,URL: http://www.open-std.org/JTC1/SC22/WG14/
1080
1081 内核文档 Documentation/process/coding-style.rst,
1082 作者 greg@kroah.com 发表于 OLS 2002:
1083 http://www.kroah.com/linux/talks/ols_2002_kernel_codingstyle_talk/html/