Re: [PATCH 2/4] coding-style: show how reusing macros prevents naming collisions

[Jonathan Corbet]

Yueh-Shun Li <shamrocklee@xxxxxxxxxx> 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@xxxxxxxxxx>
> ---
>  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?

Thanks,

jon