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

[Stefano Stabellini <sstabellini@xxxxxxxxxx>]

On Mon, 9 Sep 2024, Jan Beulich wrote:
> 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 ...

Are you asking for something like this?

Omit the word "arch" from the filepath.

If you prefer an alternative wording please suggest the text. 


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

Suggested text:

Omit the words "arch" and "include/asm" from the filepath, ASM is also
prefixed.


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

Suggested text:

Omit the words "include/xen" from the filepath, XEN is always prefixed.

Please suggest a specific alternative if you prefer