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

[Stefano Stabellini <sstabellini@xxxxxxxxxx>]

On Tue, 23 Jul 2024, Jan Beulich wrote:
> 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.

I think so too. Here is my improved version, what do you think:


Header inclusion guards
-----------------------

Unless otherwise specified, all header files should include proper
guards to prevent multiple inclusions. The following naming conventions
apply:

- 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-specific headers: ASM__<architecture>__<subdir>__<filename>_H
    - arch/x86/include/asm/something.h -> ASM__X86__SOMETHING_H

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

Notes:

- Filenames and directories are converted to uppercase.
- Dashes are converted to underscores.
- Directories, subdirectories, and filenames are separated by double
  underscores.