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

[Stefano Stabellini <sstabellini@xxxxxxxxxx>]

On Wed, 24 Jul 2024, Jan Beulich wrote:
> On 24.07.2024 00:40, Stefano Stabellini wrote:
> > 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.
> 
> s/Dashes/Non-alphanumeric characters/

+1