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

[Stefano Stabellini <sstabellini@xxxxxxxxxx>]

On Tue, 1 Oct 2024, Jan Beulich wrote:
> On 30.09.2024 23:40, Stefano Stabellini wrote:
> > On Mon, 30 Sep 2024, Jan Beulich wrote:
> >> On 12.09.2024 03:13, Stefano Stabellini wrote:
> >>> Hi Jan, we have gone back and forth on this a few times, but neither
> >>> Alessandro nor I fully understand your perspective. To help streamline
> >>> the process and save time for everyone, I suggest you provide an example
> >>> of the rules written in the style you believe is appropriate. Once you
> >>> set the initial direction, Alessandro and I can continue and complete
> >>> the rest in that preferred style.
> >>
> >> Header inclusion guards
> >> -----------------------
> >>
> >> Unless otherwise specified, all header files should include proper
> >> guards to prevent multiple inclusions. The following naming conventions
> >> apply:
> >>
> >> - Guard names are derived from directory path underneath xen/ and the
> >>   actual file name.  Path components are separated by double underscores.
> >>   Alphabetic characters are converted to upper case.  Non-alphanumeric
> >>   characters are replaced by single underscores.
> >> - Certain directory components are omitted, to keep identifier length
> >>   bounded:
> >>   - The top level include/,
> >>   - Any architecture's arch/<arch>/include/asm/ collapses to
> >>     ASM__<ARCH>__,
> >>   - Architecture-specific private files' arch/.
> >>
> >> For example:
> >>
> >> - Xen headers: XEN__<filename>_H
> >>   - include/xen/something.h -> XEN__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
> >>
> >> - Private headers: <dir>__<filename>_H
> >>   - arch/arm/arm64/lib/something.h -> ARM__ARM64__LIB__SOMETHING_H
> >>   - arch/x86/lib/something.h -> X86__LIB__SOMETHING_H
> >>   - common/something.h -> COMMON__SOMETHING_H
> >>
> >> Note that this requires some discipline on the naming of future new
> >> sub-directories: There shouldn't be any random asm/ one anywhere, for
> > 
> > I would remove the word "random"
> 
> Fine with me; perhaps use "other" in its place?

yes, that's better


> >> example.  Nor should any new ports be named the same as top-level (within
> >> xen/) directories.  Which may in turn require some care if any new top-
> >> level directories were to be added.  Rule of thumb: Whenever a new sub-
> >> directory is added, check the rules for no collisions to result.
> > 
> > I guess you meant "no collisions among the results" ?
> 
> No, that would be insufficient. I specifically mean to say that there
> should be no _potential_ for collisions, i.e. not just "among the
> results", but also for hypothetical files added underneath such new
> subdirs. Would "for no collisions to potentially result" be more clear
> from you perspective?

Yes that's clearer. Maybe this works better from an English point of
view:

Rule of thumb: Whenever adding a new subdirectory, check the rules to
prevent any potential collisions.