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. + 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. -- 2.42.0
