| Message ID | 20231201184728.31766-1-julien@xen.org (mailing list archive) |
|---|---|
| State | Superseded |
| Headers | show |
| Series | CODING_STYLE: Add a section of the naming convention | expand |
On 01/12/2023 18:47, Julien Grall wrote: > From: Julien Grall <jgrall@amazon.com> > > Several maintainers have expressed a stronger preference > to use '-' when in filename and option that contains multiple > words. > > So document it in CODING_STYLE. > > Signed-off-by: Julien Grall <jgrall@amazon.com> > --- > CODING_STYLE | 9 +++++++++ > 1 file changed, 9 insertions(+) > > diff --git a/CODING_STYLE b/CODING_STYLE > index ced3ade5a6fb..afd09177745b 100644 > --- a/CODING_STYLE > +++ b/CODING_STYLE > @@ -144,6 +144,15 @@ separate lines and each line should begin with a leading '*'. > * Note beginning and end markers on separate lines and leading '*'. > */ > > +Naming convention > +----------------- > + > +When command line option or filename contain multiple words, a '-' > +should be to separate them. E.g. 'timer-works'. > + > +Note that some of the option and filename are using '_'. This is now > +deprecated. Urgh, I sent the wrong draft :(. This is the wording I wanted to propose: +Naming convention +----------------- + +'-' should be used to separate words in commandline options and filenames. +E.g. timer-works. + +Note that some of the options and filenames are using '_'. This is now +deprecated. + Cheers,
On 01.12.2023 19:49, Julien Grall wrote: > +Naming convention > +----------------- > + > +'-' should be used to separate words in commandline options and filenames. > +E.g. timer-works. > + > +Note that some of the options and filenames are using '_'. This is now > +deprecated. I certainly appreciate and second the intent, yet I'm afraid "Naming convention" in the doc would (to me at least) first and foremost talk about identifiers used in the various source files. If this really is to be about only file names and command line options, then I think the heading would better say so. Alternatively a clear indication would want adding that text about identifiers is supposed to be here, but is yet to be written. (The text itself, for the intended purpose, reads fine to me, fwiw.) Jan
> On 1 Dec 2023, at 18:49, Julien Grall <julien@xen.org> wrote: > > > > On 01/12/2023 18:47, Julien Grall wrote: >> From: Julien Grall <jgrall@amazon.com> >> Several maintainers have expressed a stronger preference >> to use '-' when in filename and option that contains multiple >> words. >> So document it in CODING_STYLE. >> Signed-off-by: Julien Grall <jgrall@amazon.com> >> --- >> CODING_STYLE | 9 +++++++++ >> 1 file changed, 9 insertions(+) >> diff --git a/CODING_STYLE b/CODING_STYLE >> index ced3ade5a6fb..afd09177745b 100644 >> --- a/CODING_STYLE >> +++ b/CODING_STYLE >> @@ -144,6 +144,15 @@ separate lines and each line should begin with a leading '*'. >> * Note beginning and end markers on separate lines and leading '*'. >> */ >> +Naming convention >> +----------------- >> + >> +When command line option or filename contain multiple words, a '-' >> +should be to separate them. E.g. 'timer-works'. >> + >> +Note that some of the option and filename are using '_'. This is now >> +deprecated. > > Urgh, I sent the wrong draft :(. This is the wording I wanted to propose: > > +Naming convention > +----------------- > + > +'-' should be used to separate words in commandline options and filenames. > +E.g. timer-works. > + > +Note that some of the options and filenames are using '_'. This is now > +deprecated. > + > Hi Julien, Can we make an exception for python files that are meant to be used as module? Because modules containing ‘-‘ cannot be imported using ‘import’ keyword and needs another way to do them which is not conventional Cheers, Luca > Cheers, > > -- > Julien Grall >
Hi Luca, On 04/12/2023 11:20, Luca Fancellu wrote: > > >> On 1 Dec 2023, at 18:49, Julien Grall <julien@xen.org> wrote: >> >> >> >> On 01/12/2023 18:47, Julien Grall wrote: >>> From: Julien Grall <jgrall@amazon.com> >>> Several maintainers have expressed a stronger preference >>> to use '-' when in filename and option that contains multiple >>> words. >>> So document it in CODING_STYLE. >>> Signed-off-by: Julien Grall <jgrall@amazon.com> >>> --- >>> CODING_STYLE | 9 +++++++++ >>> 1 file changed, 9 insertions(+) >>> diff --git a/CODING_STYLE b/CODING_STYLE >>> index ced3ade5a6fb..afd09177745b 100644 >>> --- a/CODING_STYLE >>> +++ b/CODING_STYLE >>> @@ -144,6 +144,15 @@ separate lines and each line should begin with a leading '*'. >>> * Note beginning and end markers on separate lines and leading '*'. >>> */ >>> +Naming convention >>> +----------------- >>> + >>> +When command line option or filename contain multiple words, a '-' >>> +should be to separate them. E.g. 'timer-works'. >>> + >>> +Note that some of the option and filename are using '_'. This is now >>> +deprecated. >> >> Urgh, I sent the wrong draft :(. This is the wording I wanted to propose: >> >> +Naming convention >> +----------------- >> + >> +'-' should be used to separate words in commandline options and filenames. >> +E.g. timer-works. >> + >> +Note that some of the options and filenames are using '_'. This is now >> +deprecated. >> + >> > > Hi Julien, > > Can we make an exception for python files that are meant to be used as module? > Because modules containing ‘-‘ cannot be imported using ‘import’ keyword and > needs another way to do them which is not conventional I am not sure this needs to be written down explicitely. At the top of the file we have: "The Xen coding style described below is the coding style used by the Xen hypervisor itself (xen/*) as well as various associated low-level libraries (e.g. tools/libxc/*). An exception is made for files which are imported from an external source. In these cases the prevailing coding style of the upstream source is generally used (commonly the Linux coding style). Other parts of the code base may use other coding styles, sometimes explicitly (e.g. tools/libxl/CODING_STYLE) but often implicitly (Linux coding style is fairly common). In general you should copy the style of the surrounding code. If you are unsure please ask." and I would not describe Python as low-level. Cheers,
> On 4 Dec 2023, at 11:31, Julien Grall <julien@xen.org> wrote: > > Hi Luca, > > On 04/12/2023 11:20, Luca Fancellu wrote: >>> On 1 Dec 2023, at 18:49, Julien Grall <julien@xen.org> wrote: >>> >>> >>> >>> On 01/12/2023 18:47, Julien Grall wrote: >>>> From: Julien Grall <jgrall@amazon.com> >>>> Several maintainers have expressed a stronger preference >>>> to use '-' when in filename and option that contains multiple >>>> words. >>>> So document it in CODING_STYLE. >>>> Signed-off-by: Julien Grall <jgrall@amazon.com> >>>> --- >>>> CODING_STYLE | 9 +++++++++ >>>> 1 file changed, 9 insertions(+) >>>> diff --git a/CODING_STYLE b/CODING_STYLE >>>> index ced3ade5a6fb..afd09177745b 100644 >>>> --- a/CODING_STYLE >>>> +++ b/CODING_STYLE >>>> @@ -144,6 +144,15 @@ separate lines and each line should begin with a leading '*'. >>>> * Note beginning and end markers on separate lines and leading '*'. >>>> */ >>>> +Naming convention >>>> +----------------- >>>> + >>>> +When command line option or filename contain multiple words, a '-' >>>> +should be to separate them. E.g. 'timer-works'. >>>> + >>>> +Note that some of the option and filename are using '_'. This is now >>>> +deprecated. >>> >>> Urgh, I sent the wrong draft :(. This is the wording I wanted to propose: >>> >>> +Naming convention >>> +----------------- >>> + >>> +'-' should be used to separate words in commandline options and filenames. >>> +E.g. timer-works. >>> + >>> +Note that some of the options and filenames are using '_'. This is now >>> +deprecated. >>> + >>> >> Hi Julien, >> Can we make an exception for python files that are meant to be used as module? >> Because modules containing ‘-‘ cannot be imported using ‘import’ keyword and >> needs another way to do them which is not conventional > > I am not sure this needs to be written down explicitely. At the top of the file we have: > > "The Xen coding style described below is the coding style used by the > Xen hypervisor itself (xen/*) as well as various associated low-level > libraries (e.g. tools/libxc/*). > > An exception is made for files which are imported from an external > source. In these cases the prevailing coding style of the upstream > source is generally used (commonly the Linux coding style). > > Other parts of the code base may use other coding styles, sometimes > explicitly (e.g. tools/libxl/CODING_STYLE) but often implicitly (Linux > coding style is fairly common). In general you should copy the style > of the surrounding code. If you are unsure please ask." > > and I would not describe Python as low-level. Ok makes sense to me! Thanks > > Cheers, > > -- > Julien Grall
Hi Jan, On 04/12/2023 09:39, Jan Beulich wrote: > On 01.12.2023 19:49, Julien Grall wrote: >> +Naming convention >> +----------------- >> + >> +'-' should be used to separate words in commandline options and filenames. >> +E.g. timer-works. >> + >> +Note that some of the options and filenames are using '_'. This is now >> +deprecated. > > I certainly appreciate and second the intent, yet I'm afraid "Naming convention" > in the doc would (to me at least) first and foremost talk about identifiers used > in the various source files. If this really is to be about only file names and > command line options, then I think the heading would better say so. Alternatively > a clear indication would want adding that text about identifiers is supposed to > be here, but is yet to be written. (The text itself, for the intended purpose, > reads fine to me, fwiw.) Right now, I don't have any plan to document the naming convention for identifiers. In fact, I don't know if we have one... So how about renaming the section to: "Naming convention for files and comand line options" Cheers,
On 04.12.2023 20:05, Julien Grall wrote: > On 04/12/2023 09:39, Jan Beulich wrote: >> On 01.12.2023 19:49, Julien Grall wrote: >>> +Naming convention >>> +----------------- >>> + >>> +'-' should be used to separate words in commandline options and filenames. >>> +E.g. timer-works. >>> + >>> +Note that some of the options and filenames are using '_'. This is now >>> +deprecated. >> >> I certainly appreciate and second the intent, yet I'm afraid "Naming convention" >> in the doc would (to me at least) first and foremost talk about identifiers used >> in the various source files. If this really is to be about only file names and >> command line options, then I think the heading would better say so. Alternatively >> a clear indication would want adding that text about identifiers is supposed to >> be here, but is yet to be written. (The text itself, for the intended purpose, > reads fine to me, fwiw.) > > Right now, I don't have any plan to document the naming convention for > identifiers. In fact, I don't know if we have one... > > So how about renaming the section to: > > "Naming convention for files and comand line options" That would be fine with me (with - nit - "command"). Then Acked-by: Jan Beulich <jbeulich@suse.com> Jan
diff --git a/CODING_STYLE b/CODING_STYLE index ced3ade5a6fb..afd09177745b 100644 --- a/CODING_STYLE +++ b/CODING_STYLE @@ -144,6 +144,15 @@ separate lines and each line should begin with a leading '*'. * Note beginning and end markers on separate lines and leading '*'. */ +Naming convention +----------------- + +When command line option or filename contain multiple words, a '-' +should be to separate them. E.g. 'timer-works'. + +Note that some of the option and filename are using '_'. This is now +deprecated. + Emacs local variables ---------------------