diff mbox series

CODING_STYLE: Add a section of the naming convention

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

Commit Message

Julien Grall Dec. 1, 2023, 6:47 p.m. UTC
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(+)

Comments

Julien Grall Dec. 1, 2023, 6:49 p.m. UTC | #1
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,
Jan Beulich Dec. 4, 2023, 9:39 a.m. UTC | #2
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
Luca Fancellu Dec. 4, 2023, 11:20 a.m. UTC | #3
> 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
>
Julien Grall Dec. 4, 2023, 11:31 a.m. UTC | #4
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,
Luca Fancellu Dec. 4, 2023, 11:46 a.m. UTC | #5
> 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
Julien Grall Dec. 4, 2023, 7:05 p.m. UTC | #6
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,
Jan Beulich Dec. 5, 2023, 7:41 a.m. UTC | #7
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 mbox series

Patch

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