1 .. include:: ../disclaimer-zh_CN.rst
2
3 :Original: :ref:`Documentation/process/4.Codin
4
5 :Translator:
6
7 时奎亮 Alex Shi <alex.shi@linux.alibaba.com
8
9 :校译:
10
11 吴想成 Wu XiangCheng <bobwxc@email.cn>
12
13 .. _cn_development_coding:
14
15 使代码正确
16 ======================
17
18 虽然一个坚实的、面向社区的设计
19 的证明都反映在代码中。它是将由
20 的代码。所以这段代码的质量决定
21
22 本节将检查编码过程。我们将从内
23 到正确的做法和相关有用的工具上
24
25 陷阱
26 ----
27
28 代码风格
29 ********
30
31 内核长期以来都有其标准的代码风
32 :ref:`Documentation/translations/zh_CN/process
33 中所述。在多数时候，该文档中描
34 大量不符合代码风格准则的代码。
35
36 首先，相信内核代码标准并不重要
37 编写代码，那么新代码将很难加入
38 对代码进行重新格式化。一个像内
39 开发人员能够快速理解其中的任何
40
41 内核的代码风格偶尔会与雇主的强
42 之前遵从内核代码风格。将代码放
43 包括控制代码样式。
44
45 另一个危害是认为已经在内核中的
46 重新格式化补丁，作为熟悉开发过
47 的一种方式，或者两者兼而有之。
48 往受到冷遇。因此，最好避免编写
49 同时顺带修复其样式是很自然的，
50
51 代码风格文档也不应该被视为绝对
52 样式（例如为了80列限制拆分行会
53
54 注意您还可以使用 ``clang-format`` 工
55 化部分代码，和审阅完整的文件以
56 可以方便地排序 ``#includes`` 、对齐
57 信息，请参阅文档 :ref:`Documentation/d
58
59 抽象层
60 ******
61
62 计算机科学教授教学生以灵活性和
63 地使用了抽象；任何涉及数百万行
64 表明，过度或过早的抽象可能和过
65 不要过度。
66
67 简单点，先考虑一个调用时始终只
68 以在需要使用它时提供的额外灵活
69 可能以某种从未被注意到的微妙方
70 的灵活性时，它并未以符合程序员
71 补丁来删除未使用的参数；一般来
72
73 隐藏硬件访问的抽象层——通常为
74 欢迎。这样的层使代码变得模糊，
75
76 另一方面，如果您发现自己从另一
77 了解一下：是否需要将这些代码中
78 实现这些功能。在整个内核中复制
79
80 #ifdef 和预处理
81 ***************
82
83 C预处理器似乎给一些C程序员带来
84 源代码中的方法。但是预处理器不
85 对编译器来说更难检查正确性。使
86 清理工作的标志。
87
88 使用#ifdef的条件编译实际上是一个
89 看到代码被铺满#ifdef块。一般规定
90 编译代码可以限制函数，如果代码
91 悄悄地优化对空函数的调用。使得
92
93 C预处理器宏存在许多危险性，包括
94 重评估。如果您试图定义宏，请考
95 函数更容易阅读，不会多次计算其
96
97 内联函数
98 ********
99
100 不过，内联函数本身也存在风险。
101 文件所固有的效率。然而，这些功
102 点都被复制一遍，所以最终会增加
103 造成压力，从而大大降低执行速度
104 函数调用的成本并不高；大量创建
105
106 一般来说，内核程序员会自冒风险
107 时间/空间权衡通常不适用于当代硬
108 更紧凑的程序运行得慢。
109
110 较新的编译器越来越激进地决定一
111 “inline”关键字可能不仅仅是过度
112
113 锁
114 **
115
116 2006年5月，“deviceescape”网络堆栈
117 这是一个受欢迎的消息；Linux中对
118 Deviceescape堆栈承诺修复这种情况。
119 正进入主线。发生了什么？
120
121 这段代码出现了许多闭门造车的迹
122 设计。在合并这个网络堆栈（现在
123 改造。
124
125 曾经，Linux内核代码可以在不考虑
126 开发。然而现在，这个文档就是在
127 为提高响应能力所做的工作也会提
128 的日子早已远去。
129
130 可以由多个线程并发访问的任何资
131 的代码应该谨记这一要求；事后修
132 时间充分了解可用的锁原语，以便
133 很难进入主线。
134
135 回归
136 ****
137
138 最后一个值得一提的危险是回归：
139 （这也可能会带来很大的改进）。
140 最不受欢迎的问题。除了少数例外
141 将被取消。最好首先避免回归发生
142
143 人们常常争论，如果回归带来的功
144 如果它破坏了一个系统却为十个系
145 Linus对这个问题给出了最佳答案:
146
147 ::
148
149 所以我们不会通过引入新问
150 是否真的有进展。是前进两
151
152 （http://lwn.net/Articles/243460/）
153
154 特别不受欢迎的一种回归类型是用
155 就必须无限期地支持它。这一事实
156 不能以不兼容的方式进行更改，所
157 的思考、清晰的文档和广泛的审查
158
159
160 代码检查工具
161 ------------
162
163 至少目前，编写无错误代码仍然是
164 的是，在代码进入主线内核之前，
165 员已经提供了一系列令人印象深刻
166 发现的任何问题都是一个以后不会
167 自动化工具。
168
169 第一步是注意编译器产生的警告。
170 通常，这些警告都指向真正的问题
171 在消除警告时，注意了解真正的原
172
173 请注意，并非所有编译器警告都默
174 获得完整集合。
175
176 内核提供了几个配置选项，可以打
177 子菜单中。对于任何用于开发或测
178 您应该打开：
179
180 - FRAME_WARN 获取大于给定数量的堆
181 这些警告生成的输出可能比较冗
182
183 - DEBUG_OBJECTS 将添加代码以跟踪内
184 时发出警告。如果你要添加创建
185 考虑打开对象调试基础结构的支
186
187 - DEBUG_SLAB 可以发现各种内存分配
188
189 - DEBUG_SPINLOCK, DEBUG_ATOMIC_SLEEP 和 DEBU
190 锁错误。
191
192 还有很多其他调试选项，其中一些
193 一直使用。在学习可用选项上花费
194
195 其中一个较重的调试工具是锁检查
196 （spinlock或mutex）的获取和释放、获
197 它可以确保总是以相同的顺序获取
198 说，lockdep可以找到许多导致系统死
199 很痛苦（对于开发人员和用户而言
200 任何类型的非普通锁的代码在提交
201
202 作为一个勤奋的内核程序员，毫无
203 的返回状态。然而，事实上，最终
204 代码往往会出问题；如果所有这些
205 更有信心。
206
207 内核提供了一个可以做到这一点的
208 启用故障注入后，内存分配的可配
209 范围内。在启用了故障注入的情况
210 应。有关如何使用此工具的详细信
211 Documentation/fault-injection/fault-injection.
212
213 “sparse”静态分析工具可以发现其
214 和内核空间地址之间的混淆、大端
215 整数值等等。sparse必须单独安装(如
216 可以在 https://sparse.wiki.kernel.org/index
217 然后可以通过在make命令中添加“C=1
218
219 “Coccinelle”工具 :ref:`http://coccinelle
220 能够发现各种潜在的编码问题；它
221 scripts/coccinelle目录下已经打包了相
222 “make coccicheck”将运行这些语义补
223 :ref:`Documentation/dev-tools/coccinelle.rst <
224
225
226 其他类型的可移植性错误最好通过
227 或Blackfin开发板，您仍然可以执行
228 交叉编译器：
229
230 https://www.kernel.org/pub/tools/cross
231
232 花一些时间安装和使用这些编译器
233
234 文档
235 ----
236
237 文档通常比内核开发规则更为例外
238 到内核中的过程，使其他开发人员
239 下，添加文档已基本上是强制性的
240
241 任何补丁的第一个文档是其关联的
242 方案的形式、处理补丁的人员、对
243 其他内容。确保变更日志说明了*为
244
245 任何添加新用户空间接口的代码—
246 的文档，该文档使用户空间开发人
247 Documentation/ABI/README，了解如何此文
248
249 文档 :ref:`Documentation/admin-guide/kernel-
250 描述了内核的所有引导时间参数。
251 条目。
252
253 任何新的配置选项都必须附有帮助
254 希望何时使用它们。
255
256 许多子系统的内部API信息通过专门
257 “kernel-doc”脚本以多种方式提取和
258 工作，则应该维护它们，并根据需
259 的领域中，为将来添加kerneldoc注释
260 来说是一个有用的活动。这些注释
261 :ref:`Documentation/doc-guide/ <doc_guide>`
262
263 任何阅读大量现有内核代码的人都
264 对新代码的要求比过去更高；合并
265 详细注释的代码。代码本身应该是
266
267 某些事情应该总是被注释。使用内
268 屏障。数据结构的锁规则通常需要
269 的文档。应该指出代码中分立的位
270 错误的“清理”的事情都需要一个
271
272
273 内部API更改
274 -----------
275
276 内核提供给用户空间的二进制接口
277 是高度流动的，当需要时可以更改
278 仅因为它不满足你的需求导致无法
279 作为内核开发人员，您有权进行此
280
281 的确可以进行API更改，但更改必须
282 附带关于更改内容和必要原因的描
283 埋在一个更大的补丁中。
284
285 另一个要点是，更改内部API的开发
286 对于一个广泛使用的函数，这个责
287 开发人员正在做的工作相冲突。不
288 可靠的。请注意，coccinelle工具可以
289
290 在进行不兼容的API更改时，应尽可
291 到该接口的树内用处。它还将警告
292 代码不是内核开发人员需要担心的
293 的困难。
Linux® is a registered trademark of Linus Torvalds in the United States and other countries.
TOMOYO® is a registered trademark of NTT DATA CORPORATION.