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

[Jan Beulich <jbeulich@xxxxxxxx>]

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?

>> 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?

Jan