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

lists.openwall.net		lists / announce owl-users owl-dev john-users john-dev passwdqc-users yescrypt popa3d-users / oss-security kernel-hardening musl sabotage tlsify passwords / crypt-dev xvendor / Bugtraq Full-Disclosure linux-kernel linux-netdev linux-ext4 linux-hardening linux-cve-announce PHC
Open Source and information security mailing list archives

Hash Suite: Windows password security audit tool. GUI, reports in PDF.

[<prev] [next>] [<thread-prev] [thread-next>] [day] [month] [year] [list]

Message-ID: <20240108160746.177421-5-shamrocklee@posteo.net>
Date: Mon,  8 Jan 2024 16:03:25 +0000
From: Yueh-Shun Li <shamrocklee@...teo.net>
To: Alex Shi <alexs@...nel.org>,
	Yanteng Si <siyanteng@...ngson.cn>
Cc: Yueh-Shun Li <shamrocklee@...teo.net>,
	linux-doc@...r.kernel.org,
	linux-kernel@...r.kernel.org
Subject: [PATCH 4/4] doc/zh_CN: coding-style: update content of section 18

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@...teo.net>
---
 .../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