|
[Date Prev][Date Next][Thread Prev][Thread Next][Date Index][Thread Index] Re: [XEN PATCH v6] CODING_STYLE: Add a section on header guards naming conventions
On 10.09.2024 06:57, Stefano Stabellini wrote: > 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 Looks like I still didn't get across my point: The verbal description that's ahead of all of the examples should be complete enough to describe the whole set of rules, in sufficiently abstract terms. Then the examples will be easy to prove as fitting those rules, and it will be easy to derive the naming for further identifiers. IOW - no, I'm not asking for the examples to be further commented, but for the naming rules to be _fully_ spelled out. Jan
|
 |
Lists.xenproject.org is hosted with RackSpace, monitoring our |