[PATCH 4/4] doc/zh_CN: coding-style: update content of section 18

From: Yueh-Shun Li
Date: Mon Jan 08 2024 - 11:18:00 EST


Update the content of the zh_CN translation of "Linux kernel coding
style" section 18, following the change proposed in the first 2 patches
in these patch series.

As a zh_TW speaker, I tried my best to compare and proofread the content
generated with OpenCC[1] with tw2s and tw2sp configurations, and
existing translation in the same file. Please kindly point out anything
I should fix.

[1]: https://github.com/BYVoid/OpenCC

Signed-off-by: Yueh-Shun Li <shamrocklee@xxxxxxxxxx>
---
.../zh_CN/process/coding-style.rst | 39 +++++++++++++++----
1 file changed, 31 insertions(+), 8 deletions(-)

diff --git a/Documentation/translations/zh_CN/process/coding-style.rst b/Documentation/translations/zh_CN/process/coding-style.rst
index fa28ef0a7fee..14ff3cdc2d0d 100644
--- a/Documentation/translations/zh_CN/process/coding-style.rst
+++ b/Documentation/translations/zh_CN/process/coding-style.rst
@@ -919,25 +919,48 @@ Linux内核布尔(bool)类型是C99 _Bool类型的别名。布尔值只能

总之,在结构体和参数中有限地使用布尔可以提高可读性。

+
18) 不要重新发明内核宏
----------------------

-头文件 include/linux/kernel.h 包含了一些宏,你应该使用它们,而不要自己写一些
-它们的变种。比如,如果你需要计算一个数组的长度,使用这个宏
+``include/linux`` 目录下的头文件提供了一些宏,你应该使用它们,而不要自己写
+一些它们的变种。比如,如果你需要计算一个数组的长度,使用
+``include/linux/array_size.h`` 提供的 ``ARRAY_SIZE()`` 宏

.. code-block:: c

- #define ARRAY_SIZE(x) (sizeof(x) / sizeof((x)[0]))
+ #include <linux/array_size.h>
+ ARRAY_SIZE(x) // The size of array x
+
+类似的,如果你要计算某结构体成员的大小,使用 ``include/linux/stddef.h`` 当
+中的 ``sizeof_field()`` 宏。
+
+还有 ``include/linux/minmax.h`` 提供能做严格的类型检查的 ``min()`` 和
+``max()`` 宏,如果你需要可以使用它们。

-类似的,如果你要计算某结构体成员的大小,使用
+使用共用头文件所提供的宏也能避免命名冲突。比如说,如果有个开发者在头文件
+``foo.h`` 中定义了

.. code-block:: c

- #define sizeof_field(t, f) (sizeof(((t*)0)->f))
+ #define __stringify(x) __stringify_1(x)
+ #define __stringify_1(x) #x
+
+但另一个开发者在头文件 ``bar.h`` 中定义了
+
+.. code-block:: c
+
+ #define stringify(x) __stringify(x)
+ #define __stringify(x) #x
+
+当两个头文件都被 ``#include`` 进同一份文件,``foo.h`` 提供的工具可能会被
+``bar.h`` 破坏。
+
+如果两个头文件都使用 ``include/linux/stringify.h`` 提供的 ``__stringify()``
+宏,就不会互相干扰了。

-还有可以做严格的类型检查的 min() 和 max() 宏,如果你需要可以使用它们。你可以
-自己看看那个头文件里还定义了什么你可以拿来用的东西,如果有定义的话,你就不应
-在你的代码里自己重新定义。
+你可以自己搜索、看看那些头文件里还定义了什么你可以拿来用的东西,如果有定义的
+话,你就不应在你的代码里自己重新定义。


19) 编辑器模式行和其他需要罗嗦的事情
--
2.42.0