1 .. SPDX-License-Identifier: GPL-2.0 1 .. SPDX-License-Identifier: GPL-2.0
2 2
3 .. include:: ../disclaimer-zh_TW.rst 3 .. include:: ../disclaimer-zh_TW.rst
4 4
5 :Original: :ref:`Documentation/process/4.Codin 5 :Original: :ref:`Documentation/process/4.Coding.rst <development_coding>`
6 6
7 :Translator: 7 :Translator:
8 8
9 時奎亮 Alex Shi <alex.shi@linux.alibaba.com 9 時奎亮 Alex Shi <alex.shi@linux.alibaba.com>
10 10
11 :校譯: 11 :校譯:
12 12
13 吳想成 Wu XiangCheng <bobwxc@email.cn> 13 吳想成 Wu XiangCheng <bobwxc@email.cn>
14 胡皓文 Hu Haowen <2023002089@link.tyut.edu. !! 14 胡皓文 Hu Haowen <src.res.211@gmail.com>
15 15
16 .. _tw_development_coding: 16 .. _tw_development_coding:
17 17
18 使代碼正確 18 使代碼正確
19 ====================== 19 ======================
20 20
21 雖然一個堅實的、面向社區的設計 21 雖然一個堅實的、面向社區的設計過程有很多值得說道的，但是任何內核開發項目工作
22 的證明都反映在代碼中。它是將由 22 的證明都反映在代碼中。它是將由其他開發人員檢查併合並（或不合並）到主線樹中
23 的代碼。所以這段代碼的質量決定 23 的代碼。所以這段代碼的質量決定了項目的最終成功。
24 24
25 本節將檢查編碼過程。我們將從內 25 本節將檢查編碼過程。我們將從內核開發人員常犯的幾種錯誤開始。然後重點將轉移
26 到正確的做法和相關有用的工具上 26 到正確的做法和相關有用的工具上。
27 27
28 陷阱 28 陷阱
29 ---- 29 ----
30 30
31 代碼風格 31 代碼風格
32 ******** 32 ********
33 33
34 內核長期以來都有其標準的代碼風 34 內核長期以來都有其標準的代碼風格，如
35 :ref:`Documentation/translations/zh_CN/process 35 :ref:`Documentation/translations/zh_CN/process/coding-style.rst <tw_codingstyle>`
36 中所述。在多數時候，該文檔中描 36 中所述。在多數時候，該文檔中描述的準則至多被認爲是建議性的。因此，內核中存在
37 大量不符合代碼風格準則的代碼。 37 大量不符合代碼風格準則的代碼。這種代碼的存在會給內核開發人員帶來兩方面的危害。
38 38
39 首先，相信內核代碼標準並不重要 39 首先，相信內核代碼標準並不重要，也不強制執行。但事實上，如果沒有按照標準
40 編寫代碼，那麼新代碼將很難加入 40 編寫代碼，那麼新代碼將很難加入到內核中；許多開發人員甚至會在審查代碼之前要求
41 對代碼進行重新格式化。一個像內 41 對代碼進行重新格式化。一個像內核這麼大的代碼庫需要一些統一格式的代碼，以使
42 開發人員能夠快速理解其中的任何 42 開發人員能夠快速理解其中的任何部分。所以再也經不起奇怪格式的代碼的折騰了。
43 43
44 內核的代碼風格偶爾會與僱主的強 44 內核的代碼風格偶爾會與僱主的強制風格發生衝突。在這種情況下，必須在代碼合併
45 之前遵從內核代碼風格。將代碼放 45 之前遵從內核代碼風格。將代碼放入內核意味着以多種方式放棄一定程度的控制權——
46 包括控制代碼樣式。 46 包括控制代碼樣式。
47 47
48 另一個危害是認爲已經在內核中的 48 另一個危害是認爲已經在內核中的代碼迫切需要修復代碼樣式。開發者可能會開始編寫
49 重新格式化補丁，作爲熟悉開發過 49 重新格式化補丁，作爲熟悉開發過程的一種方式，或者作爲將其名字寫入內核變更日誌
50 的一種方式，或者兩者兼而有之。 50 的一種方式，或者兩者兼而有之。但是純代碼風格的修復被開發社區視爲噪音，它們往
51 往受到冷遇。因此，最好避免編寫 51 往受到冷遇。因此，最好避免編寫這種類型的補丁。在由於其他原因處理一段代碼的
52 同時順帶修復其樣式是很自然的， 52 同時順帶修復其樣式是很自然的，但是不應該僅爲了更改代碼樣式而更改之。
53 53
54 代碼風格文檔也不應該被視爲絕對 54 代碼風格文檔也不應該被視爲絕對不可違反的規則。如果有一個足夠的理由反對這種
55 樣式（例如爲了80列限制拆分行會 55 樣式（例如爲了80列限制拆分行會導致可讀性大大降低），那麼就這樣做吧。
56 56
57 注意您還可以使用 ``clang-format`` 工 57 注意您還可以使用 ``clang-format`` 工具來幫助您處理這些規則，快速自動重新格式
58 化部分代碼，和審閱完整的文件以 58 化部分代碼，和審閱完整的文件以發現代碼樣式錯誤、拼寫錯誤和可能的改進。它還
59 可以方便地排序 ``#includes`` 、對齊 59 可以方便地排序 ``#includes`` 、對齊變量/宏、重排文本和其他類似任務。有關詳細
60 信息，請參閱文檔 :ref:`Documentation/d !! 60 信息，請參閱文檔 :ref:`Documentation/process/clang-format.rst <clangformat>`
61 61
62 抽象層 62 抽象層
63 ****** 63 ******
64 64
65 計算機科學教授教學生以靈活性和 65 計算機科學教授教學生以靈活性和信息隱藏的名義廣泛使用抽象層。當然，內核廣泛
66 地使用了抽象；任何涉及數百萬行 66 地使用了抽象；任何涉及數百萬行代碼的項目都必須做到這一點以存續下來。但經驗
67 表明，過度或過早的抽象可能和過 67 表明，過度或過早的抽象可能和過早的優化一樣有害。抽象應用在適當層級，
68 不要過度。 68 不要過度。
69 69
70 簡單點，先考慮一個調用時始終只 70 簡單點，先考慮一個調用時始終只有一個參數且總爲零的函數。我們可以保留這個參數，
71 以在需要使用它時提供的額外靈活 71 以在需要使用它時提供的額外靈活性。不過，在那時實現了這個額外參數的代碼很有
72 可能以某種從未被注意到的微妙方 72 可能以某種從未被注意到的微妙方式被破壞——因爲它從未被使用過。或者當需要額外
73 的靈活性時，它並未以符合程序員 73 的靈活性時，它並未以符合程序員當初期望的方式來實現。內核開發人員通常會提交
74 補丁來刪除未使用的參數；一般來 74 補丁來刪除未使用的參數；一般來說，一開始就不應該添加這些參數。
75 75
76 隱藏硬件訪問的抽象層——通常爲 76 隱藏硬件訪問的抽象層——通常爲了允許大量的驅動程序兼容多個操作系統——尤其不受
77 歡迎。這樣的層使代碼變得模糊， 77 歡迎。這樣的層使代碼變得模糊，可能會造成性能損失；它們不屬於Linux內核。
78 78
79 另一方面，如果您發現自己從另一 79 另一方面，如果您發現自己從另一個內核子系統複製了大量的代碼，那麼是時候
80 瞭解一下：是否需要將這些代碼中 80 瞭解一下：是否需要將這些代碼中的部分提取到單獨的庫中，或者在更高的層次上
81 實現這些功能。在整個內核中複製 81 實現這些功能。在整個內核中複製相同的代碼沒有價值。
82 82
83 #ifdef 和預處理 83 #ifdef 和預處理
84 *************** 84 ***************
85 85
86 C預處理器似乎給一些C程序員帶來 86 C預處理器似乎給一些C程序員帶來了強大的誘惑，他們認爲它是一種將大量靈活性加入
87 源代碼中的方法。但是預處理器不 87 源代碼中的方法。但是預處理器不是C，大量使用它會導致代碼對其他人來說更難閱讀，
88 對編譯器來說更難檢查正確性。使 88 對編譯器來說更難檢查正確性。使用了大量預處理器幾乎總是代碼需要一些
89 清理工作的標誌。 89 清理工作的標誌。
90 90
91 使用#ifdef的條件編譯實際上是一個 91 使用#ifdef的條件編譯實際上是一個強大的功能，它在內核中使用。但是很少有人希望
92 看到代碼被鋪滿#ifdef塊。一般規定 92 看到代碼被鋪滿#ifdef塊。一般規定，ifdef的使用應儘可能限制在頭文件中。條件
93 編譯代碼可以限制函數，如果代碼 93 編譯代碼可以限制函數，如果代碼不存在，這些函數就直接變成空的。然後編譯器將
94 悄悄地優化對空函數的調用。使得 94 悄悄地優化對空函數的調用。使得代碼更加清晰，更容易理解。
95 95
96 C預處理器宏存在許多危險性，包括 96 C預處理器宏存在許多危險性，包括可能對具有副作用且沒有類型安全的表達式進行多
97 重評估。如果您試圖定義宏，請考 97 重評估。如果您試圖定義宏，請考慮創建一個內聯函數替代。結果相同的代碼，內聯
98 函數更容易閱讀，不會多次計算其 98 函數更容易閱讀，不會多次計算其參數，並且允許編譯器對參數和返回值執行類型檢查。
99 99
100 內聯函數 100 內聯函數
101 ******** 101 ********
102 102
103 不過，內聯函數本身也存在風險。 103 不過，內聯函數本身也存在風險。程序員可以傾心於避免函數調用和用內聯函數填充源
104 文件所固有的效率。然而，這些功 104 文件所固有的效率。然而，這些功能實際上會降低性能。因爲它們的代碼在每個調用站
105 點都被複制一遍，所以最終會增加 105 點都被複制一遍，所以最終會增加編譯內核的大小。此外，這也對處理器的內存緩存
106 造成壓力，從而大大降低執行速度 106 造成壓力，從而大大降低執行速度。通常內聯函數應該非常小，而且相對較少。畢竟
107 函數調用的成本並不高；大量創建 107 函數調用的成本並不高；大量創建內聯函數是過早優化的典型例子。
108 108
109 一般來說，內核程序員會自冒風險 109 一般來說，內核程序員會自冒風險忽略緩存效果。在數據結構課程開頭中的經典
110 時間/空間權衡通常不適用於當代硬 110 時間/空間權衡通常不適用於當代硬件。空間 *就是* 時間，因爲一個大的程序比一個
111 更緊湊的程序運行得慢。 111 更緊湊的程序運行得慢。
112 112
113 較新的編譯器越來越激進地決定一 113 較新的編譯器越來越激進地決定一個給定函數是否應該內聯。因此，隨意放置使用
114 “inline”關鍵字可能不僅僅是過度 114 “inline”關鍵字可能不僅僅是過度的，也可能是無用的。
115 115
116 鎖 116 鎖
117 ** 117 **
118 118
119 2006年5月，“deviceescape”網絡堆棧 119 2006年5月，“deviceescape”網絡堆棧在前呼後擁下以GPL發佈，並被納入主線內核。
120 這是一個受歡迎的消息；Linux中對 120 這是一個受歡迎的消息；Linux中對無線網絡的支持充其量被認爲是不合格的，而
121 Deviceescape堆棧承諾修復這種情況。 121 Deviceescape堆棧承諾修復這種情況。然而直到2007年6月（2.6.22），這段代碼才真
122 正進入主線。發生了什麼？ 122 正進入主線。發生了什麼？
123 123
124 這段代碼出現了許多閉門造車的跡 124 這段代碼出現了許多閉門造車的跡象。但一個大麻煩是，它並不是爲多處理器系統而
125 設計。在合併這個網絡堆棧（現在 125 設計。在合併這個網絡堆棧（現在稱爲mac80211）之前，需要對其進行一個鎖方案的
126 改造。 126 改造。
127 127
128 曾經，Linux內核代碼可以在不考慮 128 曾經，Linux內核代碼可以在不考慮多處理器系統所帶來的併發性問題的情況下進行
129 開發。然而現在，這個文檔就是在 129 開發。然而現在，這個文檔就是在雙核筆記本電腦上寫的。即使在單處理器系統上，
130 爲提高響應能力所做的工作也會提 130 爲提高響應能力所做的工作也會提高內核內的併發性水平。編寫內核代碼而不考慮鎖
131 的日子早已遠去。 131 的日子早已遠去。
132 132
133 可以由多個線程併發訪問的任何資 133 可以由多個線程併發訪問的任何資源（數據結構、硬件寄存器等）必須由鎖保護。新
134 的代碼應該謹記這一要求；事後修 134 的代碼應該謹記這一要求；事後修改鎖是一項相當困難的任務。內核開發人員應該花
135 時間充分了解可用的鎖原語，以便 135 時間充分了解可用的鎖原語，以便爲工作選擇正確的工具。對併發性缺乏關注的代碼
136 很難進入主線。 136 很難進入主線。
137 137
138 迴歸 138 迴歸
139 **** 139 ****
140 140
141 最後一個值得一提的危險是迴歸： 141 最後一個值得一提的危險是迴歸：它可能會引起導致現有用戶的某些東西中斷的改變
142 （這也可能會帶來很大的改進）。 142 （這也可能會帶來很大的改進）。這種變化被稱爲“迴歸”，迴歸已經成爲主線內核
143 最不受歡迎的問題。除了少數例外 143 最不受歡迎的問題。除了少數例外情況，如果迴歸不能及時修正，會導致迴歸的修改
144 將被取消。最好首先避免迴歸發生 144 將被取消。最好首先避免迴歸發生。
145 145
146 人們常常爭論，如果迴歸帶來的功 146 人們常常爭論，如果迴歸帶來的功能遠超過產生的問題，那麼迴歸是否爲可接受的。
147 如果它破壞了一個系統卻爲十個系 147 如果它破壞了一個系統卻爲十個系統帶來新的功能，爲何不改改態度呢？2007年7月，
148 Linus對這個問題給出了最佳答案: 148 Linus對這個問題給出了最佳答案:
149 149
150 :: 150 ::
151 151
152 所以我們不會通過引入新問 152 所以我們不會通過引入新問題來修復錯誤。這種方式是靠不住的，沒人知道
153 是否真的有進展。是前進兩 153 是否真的有進展。是前進兩步、後退一步，還是前進一步、後退兩步？
154 154
155 （http://lwn.net/Articles/243460/） 155 （http://lwn.net/Articles/243460/）
156 156
157 特別不受歡迎的一種迴歸類型是用 157 特別不受歡迎的一種迴歸類型是用戶空間ABI的任何變化。一旦接口被導出到用戶空間，
158 就必須無限期地支持它。這一事實 158 就必須無限期地支持它。這一事實使得用戶空間接口的創建特別具有挑戰性：因爲它們
159 不能以不兼容的方式進行更改，所 159 不能以不兼容的方式進行更改，所以必須一次就對。因此，用戶空間接口總是需要大量
160 的思考、清晰的文檔和廣泛的審查 160 的思考、清晰的文檔和廣泛的審查。
161 161
162 162
163 代碼檢查工具 163 代碼檢查工具
164 ------------ 164 ------------
165 165
166 至少目前，編寫無錯誤代碼仍然是 166 至少目前，編寫無錯誤代碼仍然是我們中很少人能達到的理想狀態。不過，我們希望做
167 的是，在代碼進入主線內核之前， 167 的是，在代碼進入主線內核之前，儘可能多地捕獲並修復這些錯誤。爲此，內核開發人
168 員已經提供了一系列令人印象深刻 168 員已經提供了一系列令人印象深刻的工具，可以自動捕獲各種各樣的隱藏問題。計算機
169 發現的任何問題都是一個以後不會 169 發現的任何問題都是一個以後不會困擾用戶的問題，因此，只要有可能，就應該使用
170 自動化工具。 170 自動化工具。
171 171
172 第一步是注意編譯器產生的警告。 172 第一步是注意編譯器產生的警告。當前版本的GCC可以檢測（並警告）大量潛在錯誤。
173 通常，這些警告都指向真正的問題 173 通常，這些警告都指向真正的問題。提交以供審閱的代碼一般不會產生任何編譯器警告。
174 在消除警告時，注意瞭解真正的原 174 在消除警告時，注意瞭解真正的原因，並儘量避免僅“修復”使警告消失而不解決其原因。
175 175
176 請注意，並非所有編譯器警告都默 176 請注意，並非所有編譯器警告都默認啓用。使用“make KCFLAGS=-W”構建內核以
177 獲得完整集合。 177 獲得完整集合。
178 178
179 內核提供了幾個配置選項，可以打 179 內核提供了幾個配置選項，可以打開調試功能；大多數配置選項位於“kernel hacking”
180 子菜單中。對於任何用於開發或測 180 子菜單中。對於任何用於開發或測試目的的內核，都應該啓用其中幾個選項。特別是，
181 您應該打開： 181 您應該打開：
182 182
183 - FRAME_WARN 獲取大於給定數量的堆 183 - FRAME_WARN 獲取大於給定數量的堆棧幀的警告。
184 這些警告生成的輸出可能比較冗 184 這些警告生成的輸出可能比較冗長，但您不必擔心來自內核其他部分的警告。
185 185
186 - DEBUG_OBJECTS 將添加代碼以跟蹤內 186 - DEBUG_OBJECTS 將添加代碼以跟蹤內核創建的各種對象的生命週期，並在出現問題
187 時發出警告。如果你要添加創建 187 時發出警告。如果你要添加創建（和導出）關於其自己的複雜對象的子系統，請
188 考慮打開對象調試基礎結構的支 188 考慮打開對象調試基礎結構的支持。
189 189
190 - DEBUG_SLAB 可以發現各種內存分配 190 - DEBUG_SLAB 可以發現各種內存分配和使用錯誤；它應該用於大多數開發內核。
191 191
192 - DEBUG_SPINLOCK, DEBUG_ATOMIC_SLEEP 和 DEBU 192 - DEBUG_SPINLOCK, DEBUG_ATOMIC_SLEEP 和 DEBUG_MUTEXES 會發現許多常見的
193 鎖錯誤。 193 鎖錯誤。
194 194
195 還有很多其他調試選項，其中一些 195 還有很多其他調試選項，其中一些將在下面討論。其中一些有顯著的性能影響，不應
196 一直使用。在學習可用選項上花費 196 一直使用。在學習可用選項上花費一些時間，可能會在短期內得到許多回報。
197 197
198 其中一個較重的調試工具是鎖檢查 198 其中一個較重的調試工具是鎖檢查器或“lockdep”。該工具將跟蹤系統中每個鎖
199 （spinlock或mutex）的獲取和釋放、獲 199 （spinlock或mutex）的獲取和釋放、獲取鎖的相對順序、當前中斷環境等等。然後，
200 它可以確保總是以相同的順序獲取 200 它可以確保總是以相同的順序獲取鎖，相同的中斷假設適用於所有情況等等。換句話
201 說，lockdep可以找到許多導致系統死 201 說，lockdep可以找到許多導致系統死鎖的場景。在部署的系統中，這種問題可能會
202 很痛苦（對於開發人員和用戶而言 202 很痛苦（對於開發人員和用戶而言）；LockDep允許提前以自動方式發現問題。具有
203 任何類型的非普通鎖的代碼在提交 203 任何類型的非普通鎖的代碼在提交合並前應在啓用lockdep的情況下運行測試。
204 204
205 作爲一個勤奮的內核程序員，毫無 205 作爲一個勤奮的內核程序員，毫無疑問，您將檢查任何可能失敗的操作（如內存分配）
206 的返回狀態。然而，事實上，最終 206 的返回狀態。然而，事實上，最終的故障復現路徑可能完全沒有經過測試。未測試的
207 代碼往往會出問題；如果所有這些 207 代碼往往會出問題；如果所有這些錯誤處理路徑都被執行了幾次，那麼您可能對代碼
208 更有信心。 208 更有信心。
209 209
210 內核提供了一個可以做到這一點的 210 內核提供了一個可以做到這一點的錯誤注入框架，特別是在涉及內存分配的情況下。
211 啓用故障注入後，內存分配的可配 211 啓用故障注入後，內存分配的可配置失敗的百分比；這些失敗可以限定在特定的代碼
212 範圍內。在啓用了故障注入的情況 212 範圍內。在啓用了故障注入的情況下運行，程序員可以看到當情況惡化時代碼如何響
213 應。有關如何使用此工具的詳細信 213 應。有關如何使用此工具的詳細信息，請參閱
214 Documentation/fault-injection/fault-injection. 214 Documentation/fault-injection/fault-injection.rst。
215 215
216 “sparse”靜態分析工具可以發現其 216 “sparse”靜態分析工具可以發現其他類型的錯誤。sparse可以警告程序員用戶空間
217 和內核空間地址之間的混淆、大端 217 和內核空間地址之間的混淆、大端序與小端序的混淆、在需要一組位標誌的地方傳遞
218 整數值等等。sparse必須單獨安裝(如 218 整數值等等。sparse必須單獨安裝(如果您的分發服務器沒有將其打包，
219 可以在 https://sparse.wiki.kernel.org/index 219 可以在 https://sparse.wiki.kernel.org/index.php/Main_page 找到）,
220 然後可以通過在make命令中添加“C=1 220 然後可以通過在make命令中添加“C=1”在代碼上運行它。
221 221
222 “Coccinelle”工具 :ref:`http://coccinelle 222 “Coccinelle”工具 :ref:`http://coccinelle.lip6.fr/ <devtools_coccinelle>`
223 能夠發現各種潛在的編碼問題；它 223 能夠發現各種潛在的編碼問題；它還可以爲這些問題提出修復方案。在
224 scripts/coccinelle目錄下已經打包了相 224 scripts/coccinelle目錄下已經打包了相當多的內核“語義補丁”；運行
225 “make coccicheck”將運行這些語義補 225 “make coccicheck”將運行這些語義補丁並報告發現的任何問題。有關詳細信息，請參閱
226 :ref:`Documentation/dev-tools/coccinelle.rst < 226 :ref:`Documentation/dev-tools/coccinelle.rst <devtools_coccinelle>`
227 227
228 228
229 其他類型的可移植性錯誤最好通過 229 其他類型的可移植性錯誤最好通過爲其他體系結構編譯代碼來發現。如果沒有S/390系統
230 或Blackfin開發板，您仍然可以執行 230 或Blackfin開發板，您仍然可以執行編譯步驟。可以在以下位置找到一大堆用於x86系統的
231 交叉編譯器： 231 交叉編譯器：
232 232
233 https://www.kernel.org/pub/tools/cross 233 https://www.kernel.org/pub/tools/crosstool/
234 234
235 花一些時間安裝和使用這些編譯器 235 花一些時間安裝和使用這些編譯器將有助於避免以後的尷尬。
236 236
237 文檔 237 文檔
238 ---- 238 ----
239 239
240 文檔通常比內核開發規則更爲例外 240 文檔通常比內核開發規則更爲例外。即便如此，足夠的文檔將有助於簡化將新代碼合併
241 到內核中的過程，使其他開發人員 241 到內核中的過程，使其他開發人員的生活更輕鬆，並對您的用戶有所幫助。在許多情況
242 下，添加文檔已基本上是強制性的 242 下，添加文檔已基本上是強制性的。
243 243
244 任何補丁的第一個文檔是其關聯的 244 任何補丁的第一個文檔是其關聯的變更日誌。日誌條目應該描述正在解決的問題、解決
245 方案的形式、處理補丁的人員、對 245 方案的形式、處理補丁的人員、對性能的任何相關影響，以及理解補丁可能需要的任何
246 其他內容。確保變更日誌說明了*爲 246 其他內容。確保變更日誌說明了*爲什麼*補丁值得應用；大量開發者未能提供這些信息。
247 247
248 任何添加新用戶空間接口的代碼— 248 任何添加新用戶空間接口的代碼——包括新的sysfs或/proc文件——都應該包含該接口
249 的文檔，該文檔使用戶空間開發人 249 的文檔，該文檔使用戶空間開發人員能夠知道他們在使用什麼。請參閱
250 Documentation/ABI/README，瞭解如何此文 250 Documentation/ABI/README，瞭解如何此文檔格式以及需要提供哪些信息。
251 251
252 文檔 :ref:`Documentation/admin-guide/kernel- 252 文檔 :ref:`Documentation/admin-guide/kernel-parameters.rst <kernelparameters>`
253 描述了內核的所有引導時間參數。 253 描述了內核的所有引導時間參數。任何添加新參數的補丁都應該向該文檔添加適當的
254 條目。 254 條目。
255 255
256 任何新的配置選項都必須附有幫助 256 任何新的配置選項都必須附有幫助文本，幫助文本需清楚地解釋這些選項以及用戶可能
257 希望何時使用它們。 257 希望何時使用它們。
258 258
259 許多子系統的內部API信息通過專門 259 許多子系統的內部API信息通過專門格式化的註釋進行記錄；這些註釋可以通過
260 “kernel-doc”腳本以多種方式提取和 260 “kernel-doc”腳本以多種方式提取和格式化。如果您在具有kerneldoc註釋的子系統中
261 工作，則應該維護它們，並根據需 261 工作，則應該維護它們，並根據需要爲外部可用的功能添加它們。即使在沒有如此記錄
262 的領域中，爲將來添加kerneldoc註釋 262 的領域中，爲將來添加kerneldoc註釋也沒有壞處；實際上，這對於剛開始開發內核的人
263 來說是一個有用的活動。這些註釋 263 來說是一個有用的活動。這些註釋的格式以及如何創建kerneldoc模板的一些信息可以在
264 :ref:`Documentation/doc-guide/ <doc_guide>` 264 :ref:`Documentation/doc-guide/ <doc_guide>` 上找到。
265 265
266 任何閱讀大量現有內核代碼的人都 266 任何閱讀大量現有內核代碼的人都會注意到，註釋的缺失往往是最值得注意的。同時，
267 對新代碼的要求比過去更高；合併 267 對新代碼的要求比過去更高；合併未註釋的代碼將更加困難。這就是說，人們並不期望
268 詳細註釋的代碼。代碼本身應該是 268 詳細註釋的代碼。代碼本身應該是自解釋的，註釋闡釋了更微妙的方面。
269 269
270 某些事情應該總是被註釋。使用內 270 某些事情應該總是被註釋。使用內存屏障時，應附上一行文字，解釋爲什麼需要設置內存
271 屏障。數據結構的鎖規則通常需要 271 屏障。數據結構的鎖規則通常需要在某個地方解釋。一般來說，主要數據結構需要全面
272 的文檔。應該指出代碼中分立的位 272 的文檔。應該指出代碼中分立的位之間不明顯的依賴性。任何可能誘使代碼管理人進行
273 錯誤的“清理”的事情都需要一個 273 錯誤的“清理”的事情都需要一個註釋來說明爲什麼要這樣做。等等。
274 274
275 275
276 內部API更改 276 內部API更改
277 ----------- 277 -----------
278 278
279 內核提供給用戶空間的二進制接口 279 內核提供給用戶空間的二進制接口不能被破壞，除非逼不得已。而內核的內部編程接口
280 是高度流動的，當需要時可以更改 280 是高度流動的，當需要時可以更改。如果你發現自己不得不處理一個內核API，或者僅
281 僅因爲它不滿足你的需求導致無法 281 僅因爲它不滿足你的需求導致無法使用特定的功能，這可能是API需要改變的一個標誌。
282 作爲內核開發人員，您有權進行此 282 作爲內核開發人員，您有權進行此類更改。
283 283
284 的確可以進行API更改，但更改必須 284 的確可以進行API更改，但更改必須是合理的。因此任何進行內部API更改的補丁都應該
285 附帶關於更改內容和必要原因的描 285 附帶關於更改內容和必要原因的描述。這種變化也應該拆分成一個單獨的補丁，而不是
286 埋在一個更大的補丁中。 286 埋在一個更大的補丁中。
287 287
288 另一個要點是，更改內部API的開發 288 另一個要點是，更改內部API的開發人員通常要負責修復內核樹中被更改破壞的任何代碼。
289 對於一個廣泛使用的函數，這個責 289 對於一個廣泛使用的函數，這個責任可以導致成百上千的變化，其中許多變化可能與其他
290 開發人員正在做的工作相沖突。不 290 開發人員正在做的工作相沖突。不用說，這可能是一項大工程，所以最好確保理由是
291 可靠的。請注意，coccinelle工具可以 291 可靠的。請注意，coccinelle工具可以幫助進行廣泛的API更改。
292 292
293 在進行不兼容的API更改時，應儘可 293 在進行不兼容的API更改時，應儘可能確保編譯器捕獲未更新的代碼。這將幫助您確保找
294 到該接口的樹內用處。它還將警告 294 到該接口的樹內用處。它還將警告開發人員樹外代碼存在他們需要響應的更改。支持樹外
295 代碼不是內核開發人員需要擔心的 295 代碼不是內核開發人員需要擔心的事情，但是我們也不必使樹外開發人員的生活有不必要
296 的困難。 296 的困難。
297 297
Linux® is a registered trademark of Linus Torvalds in the United States and other countries.
TOMOYO® is a registered trademark of NTT DATA CORPORATION.