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

[Jan Beulich <jbeulich@xxxxxxxx>]

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/

Jan

> - Directories, subdirectories, and filenames are separated by double
>   underscores.
>