Re: [XEN PATCH v6] CODING_STYLE: Add a section on header guards naming conventions

[Jan Beulich <jbeulich@xxxxxxxx>]

On 05.09.2024 17:48, Alessandro Zucchelli wrote:
> This section explains which format should be followed by header
> inclusion guards via a drop-down list of rules.
> 
> No functional change.
> 
> Signed-off-by: Alessandro Zucchelli <alessandro.zucchelli@xxxxxxxxxxx>
> 
> ---
> Changes in v6:
> - edit inclusion guards naming conventions, including more details

Yet I'm afraid that from my pov we're still not there. Specifically ...

> --- a/CODING_STYLE
> +++ b/CODING_STYLE
> @@ -159,6 +159,34 @@ Emacs local variables
>  A comment block containing local variables for emacs is permitted at
>  the end of files.  It should be:
>  
> +Header inclusion guards
> +-----------------------
> +
> +Unless otherwise specified, all header files should include proper
> +guards to prevent multiple inclusions. The following naming conventions
> +apply:

... reading this, I can't derive ...

> +- Private headers: <dir>__<filename>_H
> +    - arch/arm/arm64/lib/something.h -> ARM__ARM64__LIB__SOMETHING_H
> +    - arch/arm/arm32/lib/something.h -> ARM__ARM32__LIB__SOMETHING_H
> +    - arch/x86/lib/something.h -> X86__LIB__SOMETHING_H

... the absence of an equivalent of the arch/ part of the path. As per
my recollection we agreed on that shortening, but it needs spelling out
in the textual description. Such that it is possible to derived what to
uses as a name for, say, a header under common/, crypto/, or drivers/
(or anywhere else of course). Specifically with the further examples ...

> +- asm-generic headers: ASM_GENERIC__<filename>_H
> +    - include/asm-generic/something.h -> ASM_GENERIC__SOMETHING_H
> +
> +- arch-specific headers: ASM__<architecture>__<subdir>__<filename>_H
> +    - arch/x86/include/asm/something.h -> ASM__X86__SOMETHING_H

... here and ...

> +- Xen headers: XEN__<filename>_H
> +    - include/xen/something.h -> XEN__SOMETHING_H

... here, where more than just one path component is omitted, deriving
what's meant can end up ambiguous. Yet ambiguity is what we absolutely
want to avoid, to preempt later discussions on any such naming.

Plus I think that only once properly spelled out as rules it'll become
sufficiently clear whether there is any remaining risk of naming
collisions.

Jan