Received-SPF: pass (google.com: domain of linux-kernel+bounces-19955-linux.lists.archive=gmail.com@vger.kernel.org designates 2604:1380:4601:e00::3 as permitted sender) client-ip=2604:1380:4601:e00::3;
Precedence: bulk
MIME-Version: 1.0
Content-Type: text/plain; charset=US-ASCII;
 format=flowed
Content-Transfer-Encoding: 7bit
Date: Mon, 08 Jan 2024 18:23:21 +0000
From: Yueh-Shun Li <shamrocklee@posteo.net>
To: Jonathan Corbet <corbet@lwn.net>
Cc: Hu Haowen <src.res.211@gmail.com>, Alex Shi <alexs@kernel.org>, Yanteng
 Si <siyanteng@loongson.cn>, Randy Dunlap <rdunlap@infradead.org>,
 workflows@vger.kernel.org, linux-doc@vger.kernel.org,
 linux-kernel@vger.kernel.org
Subject: Re: [PATCH 2/4] coding-style: show how reusing macros prevents
 naming collisions
In-Reply-To: <871qaryel9.fsf@meer.lwn.net>
References: <107b6b5e-ca14-4b2b-ba2e-38ecd74c0ad3@infradead.org>
 <20240108160746.177421-1-shamrocklee@posteo.net>
 <20240108160746.177421-3-shamrocklee@posteo.net>
 <871qaryel9.fsf@meer.lwn.net>
Message-ID: <eecb9fa3e0cd84fce0b2f9e5449888a0@posteo.net>

Dear Mr. Corbet,

Thank you very much for your feed back.

On 2024-01-09 00:28, Jonathan Corbet wrote:
> Yueh-Shun Li <shamrocklee@posteo.net> writes:
> 
>> 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 <shamrocklee@posteo.net>
>> ---
>>  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.
>> +
> 
> So everything we add to our documentation has a cost in terms of reader
> attention.  We ask people to read through a lot of material now, and
> should only increase that ask for good reason.
> 
> With that context, I have to wonder whether we really need to tell our
> readers, who are supposed to be capable developers, that reuse can help
> to avoid name collisions?
> 

The motivation comes from existing inconsistency of the "__stringify()" 
macro
definition between e.g. "samples/bpf/tracex5.bpf.c" and other files.

I agree that increasing the length of the documentation without 
substantial
benefits would not be helpful for the readers, and doubling the length 
of a
section is too much for its purpose.

Should I shorten it into one sentence, like

```
On the other hand, locally-defined variants, such as ``#define 
__stringify(x) #x``,
could lead to naming collisions that break otherwise functioning 
facilities.
```

or just omit it in the next version of patches?

> Thanks,
> 
> jon

Thank you for your time and guidance.

Shamrock