1. Patchew
  2. Xen
  3. [XEN PATCH v5 00/17] xen: address violation of MISRA C:2012 Directive 4.10
  4. View patch

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

Alessandro Zucchelli posted 17 patches 1 month, 3 weeks ago
[XEN PATCH v5 16/17] CODING_STYLE: Add a section on header guards naming conventions
Posted by Alessandro Zucchelli 1 month, 3 weeks ago 
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@bugseng.com>

---
Changes in v5:
- edit inclusion guards naming conventions, according to feedback
  received
---
 CODING_STYLE | 21 +++++++++++++++++++++
 1 file changed, 21 insertions(+)

diff --git a/CODING_STYLE b/CODING_STYLE
index 7f6e9ad065..f4f26a3cd8 100644
--- 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
+
 /*
  * Local variables:
  * mode: C
-- 
2.34.1
Re: [XEN PATCH v5 16/17] CODING_STYLE: Add a section on header guards naming conventions
Posted by Jan Beulich 1 month, 3 weeks ago 
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@bugseng.com>

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.

Jan
Re: [XEN PATCH v5 16/17] CODING_STYLE: Add a section on header guards naming conventions
Posted by Stefano Stabellini 1 month, 3 weeks ago 
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@bugseng.com>
> 
> 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.
- Directories, subdirectories, and filenames are separated by double
  underscores.
Re: [XEN PATCH v5 16/17] CODING_STYLE: Add a section on header guards naming conventions
Posted by Jan Beulich 1 month, 3 weeks ago 
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@bugseng.com>
>>
>> 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.
>
Re: [XEN PATCH v5 16/17] CODING_STYLE: Add a section on header guards naming conventions
Posted by Stefano Stabellini 1 month, 3 weeks ago 
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@bugseng.com>
> >>
> >> 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

Patchew 2.1-devel-b67e4c2

© 2016 - 2024 Red Hat, Inc.