Re: [XEN PATCH v5 16/17] CODING_STYLE: Add a section on header guards naming conventions

[Jan Beulich <jbeulich@xxxxxxxx>]

On 23.07.2024 10:15, 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>

As indicated in reply to v4, this wants (imo needs) to move to the very start
of the series. No changes following the new scheme should be made without the
new scheme actually having been committed.

> --- a/CODING_STYLE
> +++ b/CODING_STYLE
> @@ -159,6 +159,27 @@ 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 differently specified all header files should have proper inclusion
> +guards in order to avoid being included multiple times.
> +The following naming conventions have been devised:
> +
> +- 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
> +
> +- asm-generic headers -> ASM_GENERIC__<filename>_H
> +    - include/asm-generic/something.h -> ASM_GENERIC__SOMETHING_H
> +
> +- arch/<architecture>/include/asm/<subdir>/<filename>.h -> 
> ASM__<architecture>__<subdir>__<filename>_H
> +    - arch/x86/include/asm/something.h -> ASM__X86__SOMETHING_H
> +
> +- include/xen -> XEN__<filename>_H
> +    - include/xen/something.h -> XEN__SOMETHING_H

While I think this expresses what we have settled on, it lack details. For
example, when to use single vs double underscores is left for the reader
to derive from the examples, which leaves room for interpretation.

Jan