From patchwork Mon Jan 8 16:03:22 2024 Content-Type: text/plain; charset="utf-8" MIME-Version: 1.0 Content-Transfer-Encoding: 7bit X-Patchwork-Submitter: Yueh-Shun Li X-Patchwork-Id: 186066 Return-Path: Delivered-To: ouuuleilei@gmail.com Received: by 2002:a05:7300:37c1:b0:101:2151:f287 with SMTP id y1csp1120286dyq; Mon, 8 Jan 2024 08:16:40 -0800 (PST) X-Google-Smtp-Source: AGHT+IHtWlgcBqmmOCSplIW2IkXXMKuq6Ytm/M4TjK30vHbgNzZw8U+Tmn9XFs+X46e1fb81W2gq X-Received: by 2002:a17:902:7485:b0:1d3:34cb:2324 with SMTP id h5-20020a170902748500b001d334cb2324mr1715344pll.88.1704730600323; Mon, 08 Jan 2024 08:16:40 -0800 (PST) ARC-Seal: i=1; a=rsa-sha256; t=1704730600; cv=none; d=google.com; s=arc-20160816; b=zO32PZhGru0JGPr9tC4bPS32AQmo0F1dhmPUWtT2I+gk61OO2yUbz9/UaI3Wcg+um+ P/io13F7OM9dm1vtpmVA7t/9EX/W+3Kt5igIgVedZHuayWxJiTefiNo5kapkpxnrlQCM vrMtHihl8tl+qGettPJPrl+ymwps9xXmJ33gumyMRB4B/7OGBCfaIXh1iOrk1VwKH1D1 tcKoghXQ7NegxQWIMNTYOxEcSd71XqwUafny21pLZ6xrOKZZ/BeExG+VB+SBozCLU3Ue 075wlQtm8eKJY3zEo9BW4uUSpAXFK2RamDca4M50aRbsJRaojaEWkYxqnbDk9UWCRM8C 6Xxw== ARC-Message-Signature: i=1; a=rsa-sha256; c=relaxed/relaxed; d=google.com; s=arc-20160816; h=content-transfer-encoding:mime-version:list-unsubscribe :list-subscribe:list-id:precedence:references:in-reply-to:message-id :date:subject:cc:to:from:dkim-signature; bh=2TdF+w5zrhQUIug68C7l06/is8F2nhLEFMWbLaguDOU=; fh=BITo/uEZRYT9j9W90zPFjCGLSRb+JfMPRXikTk4wLPM=; b=PqwC1s7wZ2FpcO1KUQtN1qUJf+c78Gx1/oD5MFCZtfMfL5SlA3oBNL2jpmO0L4aSyo C72FamOPsqWK+9CeM7UyJExWxQ6QT4fFxMjUhqKRg/CiTjEfAmtzAVyAxBI89uYE2voI It1yWX4Y3oFWKSqkchV9BjIT/c5YiM9Go2R2oV3nrDK+v/6WWj2mE6JipfMQwKC3IVMZ L6Gi7QKue3emBISzkDUSbRE/HFXvS4gB6/uBgRW2AUBREGiVUefz205YmMzfnjhLxxLa NNdyMqMscEXjn66fTMUYPHeQX60rBNfIebpjtR+ZnxCS8OL2qRBawxgptcmK8FCYUzXe qP0w== ARC-Authentication-Results: i=1; mx.google.com; dkim=pass header.i=@posteo.net header.s=2017 header.b=oAR6Gwaj; spf=pass (google.com: domain of linux-kernel+bounces-19827-ouuuleilei=gmail.com@vger.kernel.org designates 139.178.88.99 as permitted sender) smtp.mailfrom="linux-kernel+bounces-19827-ouuuleilei=gmail.com@vger.kernel.org"; dmarc=pass (p=NONE sp=NONE dis=NONE) header.from=posteo.net Received: from sv.mirrors.kernel.org (sv.mirrors.kernel.org. [139.178.88.99]) by mx.google.com with ESMTPS id jw3-20020a170903278300b001d3714f17easi99621plb.37.2024.01.08.08.16.40 for (version=TLS1_3 cipher=TLS_AES_256_GCM_SHA384 bits=256/256); Mon, 08 Jan 2024 08:16:40 -0800 (PST) Received-SPF: pass (google.com: domain of linux-kernel+bounces-19827-ouuuleilei=gmail.com@vger.kernel.org designates 139.178.88.99 as permitted sender) client-ip=139.178.88.99; Authentication-Results: mx.google.com; dkim=pass header.i=@posteo.net header.s=2017 header.b=oAR6Gwaj; spf=pass (google.com: domain of linux-kernel+bounces-19827-ouuuleilei=gmail.com@vger.kernel.org designates 139.178.88.99 as permitted sender) smtp.mailfrom="linux-kernel+bounces-19827-ouuuleilei=gmail.com@vger.kernel.org"; dmarc=pass (p=NONE sp=NONE dis=NONE) header.from=posteo.net Received: from smtp.subspace.kernel.org (wormhole.subspace.kernel.org [52.25.139.140]) (using TLSv1.2 with cipher ECDHE-RSA-AES256-GCM-SHA384 (256/256 bits)) (No client certificate requested) by sv.mirrors.kernel.org (Postfix) with ESMTPS id 1056C283F9C for ; Mon, 8 Jan 2024 16:16:40 +0000 (UTC) Received: from localhost.localdomain (localhost.localdomain [127.0.0.1]) by smtp.subspace.kernel.org (Postfix) with ESMTP id D0CDF53813; Mon, 8 Jan 2024 16:16:16 +0000 (UTC) Authentication-Results: smtp.subspace.kernel.org; dkim=pass (2048-bit key) header.d=posteo.net header.i=@posteo.net header.b="oAR6Gwaj" X-Original-To: linux-kernel@vger.kernel.org Received: from mout02.posteo.de (mout02.posteo.de [185.67.36.66]) (using TLSv1.2 with cipher ECDHE-RSA-AES256-GCM-SHA384 (256/256 bits)) (No client certificate requested) by smtp.subspace.kernel.org (Postfix) with ESMTPS id 4E2CC52F61 for ; Mon, 8 Jan 2024 16:16:12 +0000 (UTC) Authentication-Results: smtp.subspace.kernel.org; dmarc=pass (p=none dis=none) header.from=posteo.net Authentication-Results: smtp.subspace.kernel.org; spf=pass smtp.mailfrom=posteo.net Received: from submission (posteo.de [185.67.36.169]) by mout02.posteo.de (Postfix) with ESMTPS id 87889240101 for ; Mon, 8 Jan 2024 17:16:04 +0100 (CET) DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/simple; d=posteo.net; s=2017; t=1704730564; bh=X3VtHd5GjlJi8/Twrh4yAaOYDgw5xWt6nucsz68JnqU=; h=From:To:Cc:Subject:Date:Message-ID:MIME-Version: Content-Transfer-Encoding:From; b=oAR6GwajS3y8dsWT0cTJzZ++cMYORHI0OiZFlheCvbx9Bz2WOu21/mJCYSGtxDwz4 h6k3yv1V0fWP2Fvp2A3WLR/Mskuz806PGtjJxfdhQO5XwjPOaZMtPIQcYnTrQfXZP1 /I1E6cdiqypmkVIDZb60H7W/6n1eyBNDcQTg9L447vqXWyPc7Tg8xYGYs+7UE8b/Gf GsLpP9ijgW8lf4vSUdF6tG8puOM3ifhROSGQj823ibDvoI0VR3NLUIn1XOZCeyPnmc rQy51/3RE6opGSEbI/kqmwQzt7vt6cl2TGREoSDpibLb9smIP5PihqRP3GLRCT5AJU pflgMcO7yXtbw== Received: from customer (localhost [127.0.0.1]) by submission (posteo.de) with ESMTPSA id 4T7zh03SCsz9rxB; Mon, 8 Jan 2024 17:16:00 +0100 (CET) From: Yueh-Shun Li To: Jonathan Corbet Cc: Yueh-Shun Li , Randy Dunlap , Hu Haowen , Alex Shi , Yanteng Si , workflows@vger.kernel.org, linux-doc@vger.kernel.org, linux-kernel@vger.kernel.org Subject: [PATCH 1/4] coding-style: recommend split headers instead of kernel.h Date: Mon, 8 Jan 2024 16:03:22 +0000 Message-ID: <20240108160746.177421-2-shamrocklee@posteo.net> In-Reply-To: <20240108160746.177421-1-shamrocklee@posteo.net> References: <107b6b5e-ca14-4b2b-ba2e-38ecd74c0ad3@infradead.org> <20240108160746.177421-1-shamrocklee@posteo.net> Precedence: bulk X-Mailing-List: linux-kernel@vger.kernel.org List-Id: List-Subscribe: List-Unsubscribe: MIME-Version: 1.0 X-getmail-retrieved-from-mailbox: INBOX X-GMAIL-THRID: 1787539594048237702 X-GMAIL-MSGID: 1787539594048237702 In section "18) Don't re-invent the kernel macros" in "Linux kernel coding style": Recommend reusing macros from headers inside include/linux, instead of the obsolete include/linux/kernel.h Change wording - "The header file contains macros" -> "the header files provide macros" Some macros are intended to use inside the header file only, or are considered the implementation detail of other facilities. Developers are expected to determine if a macro is meant to be used outside the header file. Signed-off-by: Yueh-Shun Li --- Documentation/process/coding-style.rst | 23 +++++++++++++---------- 1 file changed, 13 insertions(+), 10 deletions(-) diff --git a/Documentation/process/coding-style.rst b/Documentation/process/coding-style.rst index 6db37a46d305..2504cb00a961 100644 --- a/Documentation/process/coding-style.rst +++ b/Documentation/process/coding-style.rst @@ -1048,27 +1048,30 @@ readable alternative if the call-sites have naked true/false constants. Otherwise limited use of bool in structures and arguments can improve readability. + 18) Don't re-invent the kernel macros ------------------------------------- -The header file include/linux/kernel.h contains a number of macros that -you should use, rather than explicitly coding some variant of them yourself. +The header files in the ``include/linux`` directory provide a number of macros +that you should use, rather than explicitly coding some variant of them +yourself. + For example, if you need to calculate the length of an array, take advantage -of the macro +of the macro ``ARRAY_SIZE()`` from ``include/linux/array_size.h`` by .. code-block:: c - #define ARRAY_SIZE(x) (sizeof(x) / sizeof((x)[0])) + #include + ARRAY_SIZE(x) // The size of array x Similarly, if you need to calculate the size of some structure member, use +``sizeof_field()`` from ``include/linux/stddef.h``. -.. code-block:: c - - #define sizeof_field(t, f) (sizeof(((t*)0)->f)) +There are also ``min()`` and ``max()`` macros in ``include/linux/minmax.h`` +that do strict type checking if you need them. -There are also min() and max() macros that do strict type checking if you -need them. Feel free to peruse that header file to see what else is already -defined that you shouldn't reproduce in your code. +Feel free to search across and peruse the header files to see what else is +already defined that you shouldn't reproduce in your code. 19) Editor modelines and other cruft From patchwork Mon Jan 8 16:03:23 2024 Content-Type: text/plain; charset="utf-8" MIME-Version: 1.0 Content-Transfer-Encoding: 7bit X-Patchwork-Submitter: Yueh-Shun Li X-Patchwork-Id: 186067 Return-Path: Delivered-To: ouuuleilei@gmail.com Received: by 2002:a05:7300:37c1:b0:101:2151:f287 with SMTP id y1csp1120866dyq; Mon, 8 Jan 2024 08:17:37 -0800 (PST) X-Google-Smtp-Source: AGHT+IFOl8vrosjnLjaMApUcsRyVWXeR9OgABHebr+yJ1yCNBfQRawlsE7mvso+mD0iVgZPhuWB9 X-Received: by 2002:a17:906:3848:b0:a23:6075:52a2 with SMTP id w8-20020a170906384800b00a23607552a2mr1674533ejc.6.1704730656943; Mon, 08 Jan 2024 08:17:36 -0800 (PST) ARC-Seal: i=1; a=rsa-sha256; t=1704730656; cv=none; d=google.com; s=arc-20160816; b=zNRQCCsbGlA7CPS5PgL9GeToKJl2jg34GZ/F3XD98V8Ck1GZ5nDTNYkDIYqqNDkFku fR3LHUfkB8fsn+R95Khq9/iiMRWhfp7mh2xbgL62VE6L69QV39pmpVDNroh0ZfCnW37X dDy+oX14HTrfYIEoCPH/62/Gn+3tEQBzzwtBmDz+Ae3L7FQXFfA7OY+1pEsEk9yTEXH2 pDzBYmHdvXV5JUpL2sUkxDRsMw14HjC6M6p3H6/Ro0TEMAbacxWRJ7eSjGczD1qs0xWm 93dOEChPA02ZwviBuF15h9IwyqvOtJ1eLIxqgsy1tauwkSb8SUUWi6f2w6cIegU3+7Pa sOjg== ARC-Message-Signature: i=1; a=rsa-sha256; c=relaxed/relaxed; d=google.com; s=arc-20160816; h=content-transfer-encoding:mime-version:list-unsubscribe :list-subscribe:list-id:precedence:references:in-reply-to:message-id :date:subject:cc:to:from:dkim-signature; bh=dZlY3RW6BcZHp8d9+132Kbyt1q2aPeG62rCc3NCL/Ow=; fh=cUwWqstLDc7ccmCnrKeoozbphs53ssrLk+suBfNEIKQ=; b=IsXfkOvndRBypgRMMlkUz+pEEdZjRA+fo5x5Dlv5EzxVzBISNnndHTOZXPJu+TwTyU ZtUWqhqtDLW0dEoC+XRSjEnb5uxVg7OWOV+GGSB4V9PtK8EBWWQOZERRMXP1ZQc4kWE4 rY7OraP3nDcxWyI6RJvQbGMPExjPZEZtmTGtpRPhCb0osu4vm85BEZHI79aoC6Mbhui4 JlHmaML7xh7s2UtlMKfo1uPyK21ILRsCVj/c6QEJDV3IcKD6B+fjk0ZvXL6tQwcv7X9S W1JAWfiZVf2QeYhZHs0Kk0FaiPGh89O9YjNE011r5s2qrE8Ty9wj4fXOu+2pTOlsDQ1S 7IZw== ARC-Authentication-Results: i=1; mx.google.com; dkim=pass header.i=@posteo.net header.s=2017 header.b=HzQVztjN; spf=pass (google.com: domain of linux-kernel+bounces-19830-ouuuleilei=gmail.com@vger.kernel.org designates 147.75.80.249 as permitted sender) smtp.mailfrom="linux-kernel+bounces-19830-ouuuleilei=gmail.com@vger.kernel.org"; dmarc=pass (p=NONE sp=NONE dis=NONE) header.from=posteo.net Received: from am.mirrors.kernel.org (am.mirrors.kernel.org. [147.75.80.249]) by mx.google.com with ESMTPS id a2-20020a1709065f8200b00a28716e1a2asi28112eju.611.2024.01.08.08.17.36 for (version=TLS1_3 cipher=TLS_AES_256_GCM_SHA384 bits=256/256); Mon, 08 Jan 2024 08:17:36 -0800 (PST) Received-SPF: pass (google.com: domain of linux-kernel+bounces-19830-ouuuleilei=gmail.com@vger.kernel.org designates 147.75.80.249 as permitted sender) client-ip=147.75.80.249; Authentication-Results: mx.google.com; dkim=pass header.i=@posteo.net header.s=2017 header.b=HzQVztjN; spf=pass (google.com: domain of linux-kernel+bounces-19830-ouuuleilei=gmail.com@vger.kernel.org designates 147.75.80.249 as permitted sender) smtp.mailfrom="linux-kernel+bounces-19830-ouuuleilei=gmail.com@vger.kernel.org"; dmarc=pass (p=NONE sp=NONE dis=NONE) header.from=posteo.net Received: from smtp.subspace.kernel.org (wormhole.subspace.kernel.org [52.25.139.140]) (using TLSv1.2 with cipher ECDHE-RSA-AES256-GCM-SHA384 (256/256 bits)) (No client certificate requested) by am.mirrors.kernel.org (Postfix) with ESMTPS id 8616B1F22458 for ; Mon, 8 Jan 2024 16:17:36 +0000 (UTC) Received: from localhost.localdomain (localhost.localdomain [127.0.0.1]) by smtp.subspace.kernel.org (Postfix) with ESMTP id BC5DA537E2; Mon, 8 Jan 2024 16:16:36 +0000 (UTC) Authentication-Results: smtp.subspace.kernel.org; dkim=pass (2048-bit key) header.d=posteo.net header.i=@posteo.net header.b="HzQVztjN" X-Original-To: linux-kernel@vger.kernel.org Received: from mout01.posteo.de (mout01.posteo.de [185.67.36.65]) (using TLSv1.2 with cipher ECDHE-RSA-AES256-GCM-SHA384 (256/256 bits)) (No client certificate requested) by smtp.subspace.kernel.org (Postfix) with ESMTPS id 76E5B5380D for ; Mon, 8 Jan 2024 16:16:32 +0000 (UTC) Authentication-Results: smtp.subspace.kernel.org; dmarc=pass (p=none dis=none) header.from=posteo.net Authentication-Results: smtp.subspace.kernel.org; spf=pass smtp.mailfrom=posteo.net Received: from submission (posteo.de [185.67.36.169]) by mout01.posteo.de (Postfix) with ESMTPS id DBCD8240029 for ; Mon, 8 Jan 2024 17:16:30 +0100 (CET) DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/simple; d=posteo.net; s=2017; t=1704730590; bh=VhNI/VyHttpB6Dc+nOmQ0eI7dT/saNfHep5H24iJdO8=; h=From:To:Cc:Subject:Date:Message-ID:MIME-Version: Content-Transfer-Encoding:From; b=HzQVztjNExNwWDrBuHzEvHtkFFb6vD0OXysV/RE2YSQAQeRZRM4R2KPi1eqBI1IE0 BSv2xCrBjDcgcfMHIjpUhv7F7AXvuX8XRuiUkCupg5ER15Ex18/IoSvHTPiCypErA9 870DCFFhsdxf6Ku/I5Bdn4tyn4/jWmgW0j+pNBTZ19BpBQFy9thMKIBdX+Xy1LGjKn ktiSoGhu0cJbFOuiyqcWbCl5Iv5BRsQl12Bl6+IAmoxmpSpOAEKunG3bM33lUuyF6b w7VL9S2/9IFb4670o/kT67shDy+0J9nn2ZRyR2cEJqPySYA83y8pVs3zf3EgzSV+PD zV6Uyu0OElw7A== Received: from customer (localhost [127.0.0.1]) by submission (posteo.de) with ESMTPSA id 4T7zhV4n4Wz9rxN; Mon, 8 Jan 2024 17:16:26 +0100 (CET) From: Yueh-Shun Li To: Jonathan Corbet Cc: Yueh-Shun Li , Hu Haowen , Alex Shi , Yanteng Si , Randy Dunlap , workflows@vger.kernel.org, linux-doc@vger.kernel.org, linux-kernel@vger.kernel.org Subject: [PATCH 2/4] coding-style: show how reusing macros prevents naming collisions Date: Mon, 8 Jan 2024 16:03:23 +0000 Message-ID: <20240108160746.177421-3-shamrocklee@posteo.net> In-Reply-To: <20240108160746.177421-1-shamrocklee@posteo.net> References: <107b6b5e-ca14-4b2b-ba2e-38ecd74c0ad3@infradead.org> <20240108160746.177421-1-shamrocklee@posteo.net> Precedence: bulk X-Mailing-List: linux-kernel@vger.kernel.org List-Id: List-Subscribe: List-Unsubscribe: MIME-Version: 1.0 X-getmail-retrieved-from-mailbox: INBOX X-GMAIL-THRID: 1787539653211679118 X-GMAIL-MSGID: 1787539653211679118 In section "18) Don't re-invent the kernel macros" in "Linux kernel coding style": Show how reusing macros from shared headers prevents naming collisions using "stringify", the one of the most widely reinvented macro, as an example. This patch aims to provide a stronger reason to reuse shared macros, by showing the risk of improvised macro variants. Signed-off-by: Yueh-Shun Li --- Documentation/process/coding-style.rst | 22 ++++++++++++++++++++++ 1 file changed, 22 insertions(+) diff --git a/Documentation/process/coding-style.rst b/Documentation/process/coding-style.rst index 2504cb00a961..1e79aba4b346 100644 --- a/Documentation/process/coding-style.rst +++ b/Documentation/process/coding-style.rst @@ -1070,6 +1070,28 @@ Similarly, if you need to calculate the size of some structure member, use There are also ``min()`` and ``max()`` macros in ``include/linux/minmax.h`` that do strict type checking if you need them. +Using existing macros provided by the shared headers also prevents naming +collisions. For example, if one developer define in ``foo.h`` + +.. code-block:: c + + #define __stringify(x) __stringify_1(x) + #define __stringify_1(x) #x + +and another define in ``bar.h`` + +.. code-block:: c + + #define stringify(x) __stringify(x) + #define __stringify(x) #x + +When both headers are ``#include``-d into the same file, the facilities provided +by ``foo.h`` might be broken by ``bar.h``. + +If both ``foo.h`` and ``bar.h`` use the macro ``__stringify()`` provided by +``include/linux/stringify.h``, they wouldn't have stepped onto each other's +toes. + Feel free to search across and peruse the header files to see what else is already defined that you shouldn't reproduce in your code. From patchwork Mon Jan 8 16:03:24 2024 Content-Type: text/plain; charset="utf-8" MIME-Version: 1.0 Content-Transfer-Encoding: 8bit X-Patchwork-Submitter: Yueh-Shun Li X-Patchwork-Id: 186068 Return-Path: Delivered-To: ouuuleilei@gmail.com Received: by 2002:a05:7300:37c1:b0:101:2151:f287 with SMTP id y1csp1120982dyq; Mon, 8 Jan 2024 08:17:52 -0800 (PST) X-Google-Smtp-Source: AGHT+IErPer1gce6p5uf3QLOv++v8uEZEkDofOxjKpLnTfdn2CFDFDDCaOWjGK3cyL/kNCkczecg X-Received: by 2002:a05:6358:89b:b0:175:9a73:4587 with SMTP id m27-20020a056358089b00b001759a734587mr597327rwj.57.1704730672401; Mon, 08 Jan 2024 08:17:52 -0800 (PST) ARC-Seal: i=1; a=rsa-sha256; t=1704730672; cv=none; d=google.com; s=arc-20160816; b=FnZMD58+anNJHb5k6rRMNC+Rl1QVJruT7r/EQ2wRMSofXPKy8IrEWcUdd9dZwBRSqx onEnxVV4N33FS5X8n9LuAB7G93X6z8hFvgtFvKiSD8VE2hhJL5OyXHJJMQCI47FqLiXq JpamoWVgrGTEUGeTmtvGIDqju0Ai3b8ymhi7dXqfFCOdnIwKgHrL4o5n0ykyT27KYxAO O4menc2CbMPH5ipEGM8k9Qg3i3Yb5/5cjmaQoPQBu7uhehjlY55XNSKxIoCWDf4SIbMP Ne2GX7Y/DlzOwqpk+6aV58Tl3EP3hD9yWzRVjf0k7VQ4linvYx8sbBEwrF7pYvdnB9hm pO0w== ARC-Message-Signature: i=1; a=rsa-sha256; c=relaxed/relaxed; d=google.com; s=arc-20160816; h=content-transfer-encoding:mime-version:list-unsubscribe :list-subscribe:list-id:precedence:references:in-reply-to:message-id :date:subject:cc:to:from:dkim-signature; bh=Yit4eM31HWN/VRPsQHzY21xWPPCZwj9x8fUbVUZt6Rg=; fh=0GZNLmWOen10wn2DnOVc4cDlVeEIgJYO3jZDyoxWLiI=; b=RAb08CBuSS6RZyuXsj2Mwl8pY5wvVdlayCvq66L4XCqzTFrNizF9HcCzt5y/rwTesg riH/uLtGfoh7qGbnCW+hEVftEhD67xGx0C/r8qqMG9Jecr8RffqApqHUJWXF/ZLXLDy9 JeV4aafwYt+mmbZdjhow3QQLtJ20rvNLrdgGqkNyAFI55VzoBm6q7cUEh1bprm6PqZIc A7ImA/mlMb3vH9UPC8IP4zL6+S5FeZ+jIG5BUEahIwY+AGDrPmkJTojn02FUqF+x7f5B w0Wfc65toghhBFOanysSB/QZSIxI2fsF8rajAgWcyjL332wYFjjQI97UOyRNlq/JpWlS LgQQ== ARC-Authentication-Results: i=1; mx.google.com; dkim=pass header.i=@posteo.net header.s=2017 header.b=hfeYGviL; spf=pass (google.com: domain of linux-kernel+bounces-19831-ouuuleilei=gmail.com@vger.kernel.org designates 2604:1380:45d1:ec00::1 as permitted sender) smtp.mailfrom="linux-kernel+bounces-19831-ouuuleilei=gmail.com@vger.kernel.org"; dmarc=pass (p=NONE sp=NONE dis=NONE) header.from=posteo.net Received: from ny.mirrors.kernel.org (ny.mirrors.kernel.org. [2604:1380:45d1:ec00::1]) by mx.google.com with ESMTPS id gb5-20020a05622a598500b0042994c03668si18981qtb.755.2024.01.08.08.17.52 for (version=TLS1_3 cipher=TLS_AES_256_GCM_SHA384 bits=256/256); Mon, 08 Jan 2024 08:17:52 -0800 (PST) Received-SPF: pass (google.com: domain of linux-kernel+bounces-19831-ouuuleilei=gmail.com@vger.kernel.org designates 2604:1380:45d1:ec00::1 as permitted sender) client-ip=2604:1380:45d1:ec00::1; Authentication-Results: mx.google.com; dkim=pass header.i=@posteo.net header.s=2017 header.b=hfeYGviL; spf=pass (google.com: domain of linux-kernel+bounces-19831-ouuuleilei=gmail.com@vger.kernel.org designates 2604:1380:45d1:ec00::1 as permitted sender) smtp.mailfrom="linux-kernel+bounces-19831-ouuuleilei=gmail.com@vger.kernel.org"; dmarc=pass (p=NONE sp=NONE dis=NONE) header.from=posteo.net Received: from smtp.subspace.kernel.org (wormhole.subspace.kernel.org [52.25.139.140]) (using TLSv1.2 with cipher ECDHE-RSA-AES256-GCM-SHA384 (256/256 bits)) (No client certificate requested) by ny.mirrors.kernel.org (Postfix) with ESMTPS id 268A01C22FBF for ; Mon, 8 Jan 2024 16:17:52 +0000 (UTC) Received: from localhost.localdomain (localhost.localdomain [127.0.0.1]) by smtp.subspace.kernel.org (Postfix) with ESMTP id 6EF895467C; Mon, 8 Jan 2024 16:16:49 +0000 (UTC) Authentication-Results: smtp.subspace.kernel.org; dkim=pass (2048-bit key) header.d=posteo.net header.i=@posteo.net header.b="hfeYGviL" X-Original-To: linux-kernel@vger.kernel.org Received: from mout01.posteo.de (mout01.posteo.de [185.67.36.65]) (using TLSv1.2 with cipher ECDHE-RSA-AES256-GCM-SHA384 (256/256 bits)) (No client certificate requested) by smtp.subspace.kernel.org (Postfix) with ESMTPS id 3460A5465D for ; Mon, 8 Jan 2024 16:16:45 +0000 (UTC) Authentication-Results: smtp.subspace.kernel.org; dmarc=pass (p=none dis=none) header.from=posteo.net Authentication-Results: smtp.subspace.kernel.org; spf=pass smtp.mailfrom=posteo.net Received: from submission (posteo.de [185.67.36.169]) by mout01.posteo.de (Postfix) with ESMTPS id 69C9D24002A for ; Mon, 8 Jan 2024 17:16:43 +0100 (CET) DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/simple; d=posteo.net; s=2017; t=1704730603; bh=i725bwQMCd01Orv6abs3xlOUBm43RkTh68m2tAj/kj8=; h=From:To:Cc:Subject:Date:Message-ID:MIME-Version: Content-Transfer-Encoding:From; b=hfeYGviLiV5nx/uAlkvRGMTGX57uSbquPKBtr/ZgxfNC4h/zg3HehsAI9u89pKG7v 2m8Gap1ZTW3DHpYKKanAAOk8BCerOUsNwYgLp9BEcBr2yHAbOg4WLhOxhuo4jcdTm7 mFWIvq11IYy0J8INb8s97LsTaVredjltf0cchw8ibyHWtwnFktpb+TXLyI7hUe1qn2 jUaXYDFraMUJgdfkuN4WtEkXh7YFDwR1Z77jgs14GEt31F5+8/6WrPND16+wt0Ibky HmjB0WJhab6OPDyMymuIv33BcKpkXMvrq/xf7TgoIgclpd6YB3qo1dB3l+68hDuF3F xEYRvGAt1p3og== Received: from customer (localhost [127.0.0.1]) by submission (posteo.de) with ESMTPSA id 4T7zhn114nz9rxS; Mon, 8 Jan 2024 17:16:40 +0100 (CET) From: Yueh-Shun Li To: Hu Haowen Cc: Yueh-Shun Li , linux-doc@vger.kernel.org, linux-kernel@vger.kernel.org Subject: [PATCH 3/4] doc/zh_TW: coding-style: update content for section 18 Date: Mon, 8 Jan 2024 16:03:24 +0000 Message-ID: <20240108160746.177421-4-shamrocklee@posteo.net> In-Reply-To: <20240108160746.177421-1-shamrocklee@posteo.net> References: <107b6b5e-ca14-4b2b-ba2e-38ecd74c0ad3@infradead.org> <20240108160746.177421-1-shamrocklee@posteo.net> Precedence: bulk X-Mailing-List: linux-kernel@vger.kernel.org List-Id: List-Subscribe: List-Unsubscribe: MIME-Version: 1.0 X-getmail-retrieved-from-mailbox: INBOX X-GMAIL-THRID: 1787539669564632318 X-GMAIL-MSGID: 1787539669564632318 Update the content of the zh_TW translation of "Linux kernel coding style" section 18, following the change proposed in the first 2 patches in these patch series. From the diff of between the zh_TW and zh_CN translation of the file coding-style.rst, it seems that the zh_TW files are direct character-by-character translation of the zh_CN files, without any phrase localization. This results in wording unfamilliar to zh_TW speakers. This patch reuses existing terms inside coding-style.rst (e.g. 宏 for "macros" and 頭文件 for "header files"), while localizing terms introduced in this file the first time (e.g. 搜尋 instead of 搜索 for "search"). The localization of Chinese dialects could be performed programmatically with the help of OpenCC[1] with custom configuration based on the upstream s2twp.json (zh_CN to zh_TW with Taiwanese idiom), but that is beyond the scope of this patch. [1]: https://github.com/BYVoid/OpenCC Signed-off-by: Yueh-Shun Li --- .../zh_TW/process/coding-style.rst | 39 +++++++++++++++---- 1 file changed, 31 insertions(+), 8 deletions(-) diff --git a/Documentation/translations/zh_TW/process/coding-style.rst b/Documentation/translations/zh_TW/process/coding-style.rst index 5749363de421..0197405cfec8 100644 --- a/Documentation/translations/zh_TW/process/coding-style.rst +++ b/Documentation/translations/zh_TW/process/coding-style.rst @@ -922,25 +922,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 + 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) 編輯器模式行和其他需要羅嗦的事情 From patchwork Mon Jan 8 16:03:25 2024 Content-Type: text/plain; charset="utf-8" MIME-Version: 1.0 Content-Transfer-Encoding: 8bit X-Patchwork-Submitter: Yueh-Shun Li X-Patchwork-Id: 186069 Return-Path: Delivered-To: ouuuleilei@gmail.com Received: by 2002:a05:7300:37c1:b0:101:2151:f287 with SMTP id y1csp1121138dyq; Mon, 8 Jan 2024 08:18:08 -0800 (PST) X-Google-Smtp-Source: AGHT+IFYJYgCBhJQHR5e1NS1QMkWmuKr48FdDa9lNEEDbjVi85KEJBGyLIOmkiTe7rHAGjTskroa X-Received: by 2002:a05:620a:2a03:b0:781:bf72:609e with SMTP id o3-20020a05620a2a0300b00781bf72609emr3979921qkp.90.1704730688563; Mon, 08 Jan 2024 08:18:08 -0800 (PST) ARC-Seal: i=1; a=rsa-sha256; t=1704730688; cv=none; d=google.com; s=arc-20160816; b=bbeXL31kFSTPbm4LxJiag4CVrLXbUB7BpjubV/XLFdJSHKB+JIBJ/Bshf9JEUbB560 bopW2K6/Wfe1h8wqa6HTLaQvTFU9VIH0QTX7YPm/8CUM9Zku/Fj1DmSK7p+7qAztwUMH RHERfzJvyrMumbD8vZ/FXJ1g8Bpfk4dZhP24o1+y+9AKq2W9WjDimwogpWZGvhcAB5TG NefSINqbPIlNofvc0Tcx/HpisZnmYWKoAQhyZdSsTtmMMjAAEjKzQk6H2iNLeGQhoeu3 fm3fK81EspyrElRJKYQlMzwE8/wbn0dZy3ZvZgji7RZiZhpspNYX1/R04tSW4lq9QFn/ OJcw== ARC-Message-Signature: i=1; a=rsa-sha256; c=relaxed/relaxed; d=google.com; s=arc-20160816; h=content-transfer-encoding:mime-version:list-unsubscribe :list-subscribe:list-id:precedence:references:in-reply-to:message-id :date:subject:cc:to:from:dkim-signature; bh=XdUjplQjXICAmJ92Wjn/tOJw9I+ZaPA2kyb2ykU9WXs=; fh=YkvfFJlr5NcZ6VGpD788caigMNYv+gNUBOQYT2gIZ6A=; b=wR02UhMT5pHP0TulOC0UzT0Fuugr+MFJJhbcwOljB/Eng/gn7dxZGii7DF4krsOHns r+eqyRQWYYXuR1l/oWkTGsymgknlysu4B9jkEWGmk0V1Lbgw+kZgHf2zaw7jOqXdlRWV ezjAHgc9GvN4kydJ5geT4pe4E1rOA55HXacWVcA1cognVYO7k33YL6CL/NnqcCjchXwa HCmbeSTfcBTiVU156tov7NkuRwWzKxi+955g8SIpYXf0POA35TP1sOzjaXsAzlXJMUDJ PKQAnlYvBOseebjB6GtAaU/A2VJaorInCiuKwHeG8AZlpx7/xfd9Kk0B4H5dOw8vmkMX VoFw== ARC-Authentication-Results: i=1; mx.google.com; dkim=pass header.i=@posteo.net header.s=2017 header.b=CAaevBH3; spf=pass (google.com: domain of linux-kernel+bounces-19832-ouuuleilei=gmail.com@vger.kernel.org designates 2604:1380:45d1:ec00::1 as permitted sender) smtp.mailfrom="linux-kernel+bounces-19832-ouuuleilei=gmail.com@vger.kernel.org"; dmarc=pass (p=NONE sp=NONE dis=NONE) header.from=posteo.net Received: from ny.mirrors.kernel.org (ny.mirrors.kernel.org. [2604:1380:45d1:ec00::1]) by mx.google.com with ESMTPS id p19-20020a05620a057300b0078157671738si18652qkp.219.2024.01.08.08.18.08 for (version=TLS1_3 cipher=TLS_AES_256_GCM_SHA384 bits=256/256); Mon, 08 Jan 2024 08:18:08 -0800 (PST) Received-SPF: pass (google.com: domain of linux-kernel+bounces-19832-ouuuleilei=gmail.com@vger.kernel.org designates 2604:1380:45d1:ec00::1 as permitted sender) client-ip=2604:1380:45d1:ec00::1; Authentication-Results: mx.google.com; dkim=pass header.i=@posteo.net header.s=2017 header.b=CAaevBH3; spf=pass (google.com: domain of linux-kernel+bounces-19832-ouuuleilei=gmail.com@vger.kernel.org designates 2604:1380:45d1:ec00::1 as permitted sender) smtp.mailfrom="linux-kernel+bounces-19832-ouuuleilei=gmail.com@vger.kernel.org"; dmarc=pass (p=NONE sp=NONE dis=NONE) header.from=posteo.net Received: from smtp.subspace.kernel.org (wormhole.subspace.kernel.org [52.25.139.140]) (using TLSv1.2 with cipher ECDHE-RSA-AES256-GCM-SHA384 (256/256 bits)) (No client certificate requested) by ny.mirrors.kernel.org (Postfix) with ESMTPS id 503811C22FF0 for ; Mon, 8 Jan 2024 16:18:08 +0000 (UTC) Received: from localhost.localdomain (localhost.localdomain [127.0.0.1]) by smtp.subspace.kernel.org (Postfix) with ESMTP id 0B63D54BD3; Mon, 8 Jan 2024 16:16:58 +0000 (UTC) Authentication-Results: smtp.subspace.kernel.org; dkim=pass (2048-bit key) header.d=posteo.net header.i=@posteo.net header.b="CAaevBH3" X-Original-To: linux-kernel@vger.kernel.org Received: from mout01.posteo.de (mout01.posteo.de [185.67.36.65]) (using TLSv1.2 with cipher ECDHE-RSA-AES256-GCM-SHA384 (256/256 bits)) (No client certificate requested) by smtp.subspace.kernel.org (Postfix) with ESMTPS id E1DC954736 for ; Mon, 8 Jan 2024 16:16:53 +0000 (UTC) Authentication-Results: smtp.subspace.kernel.org; dmarc=pass (p=none dis=none) header.from=posteo.net Authentication-Results: smtp.subspace.kernel.org; spf=pass smtp.mailfrom=posteo.net Received: from submission (posteo.de [185.67.36.169]) by mout01.posteo.de (Postfix) with ESMTPS id 41B6A240028 for ; Mon, 8 Jan 2024 17:16:52 +0100 (CET) DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/simple; d=posteo.net; s=2017; t=1704730612; bh=FSKcWsQ5mtlwkCpoTpXGMOT6OsAb8LvcvEc/sUGr2VU=; h=From:To:Cc:Subject:Date:Message-ID:MIME-Version: Content-Transfer-Encoding:From; b=CAaevBH3V6YyG0d8ShmWsQfffeLzQeCzOuqDjG3fTJ5UP16tN/extBLKsb1kyHN8E RWjsOvPT1fIHR5kRDbF8LwgpoZXSyH0yCVjlfDEVr4Co83FsQ/evQqMbhEQBvSqpz3 wK5/PxtRlDUdYby8ytb0+7CR1KUYzyIXXspo6EQbTNjzl2/nXjGqQGm0hSnNHG8Sae WykSkkO1Cv967G7diIZ4d9/KD8JzlbZkIAmPl4UlRGyTUlboTVY1SuWQLZzFSNVlJJ KV5NuCegkufYWrRfbz+Gm0qDekkpjx1QTTBw3rqC1kc/PUKNuro/Ta0Eg/FgGWWD8K 9+Uddbnyj3enw== Received: from customer (localhost [127.0.0.1]) by submission (posteo.de) with ESMTPSA id 4T7zhx4HD5z9rxF; Mon, 8 Jan 2024 17:16:49 +0100 (CET) From: Yueh-Shun Li To: Alex Shi , Yanteng Si Cc: Yueh-Shun Li , linux-doc@vger.kernel.org, linux-kernel@vger.kernel.org Subject: [PATCH 4/4] doc/zh_CN: coding-style: update content of section 18 Date: Mon, 8 Jan 2024 16:03:25 +0000 Message-ID: <20240108160746.177421-5-shamrocklee@posteo.net> In-Reply-To: <20240108160746.177421-1-shamrocklee@posteo.net> References: <107b6b5e-ca14-4b2b-ba2e-38ecd74c0ad3@infradead.org> <20240108160746.177421-1-shamrocklee@posteo.net> Precedence: bulk X-Mailing-List: linux-kernel@vger.kernel.org List-Id: List-Subscribe: List-Unsubscribe: MIME-Version: 1.0 X-getmail-retrieved-from-mailbox: INBOX X-GMAIL-THRID: 1787539686577793350 X-GMAIL-MSGID: 1787539686577793350 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 --- .../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 + 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) 编辑器模式行和其他需要罗嗦的事情