Re: [PATCH] CODING_STYLE: Add a section of the naming convention

From: Jan Beulich <jbeulich@suse.com>
To: George Dunlap <george.dunlap@cloud.com>,
	Andrew Cooper <andrew.cooper3@citrix.com>
Cc: xen-devel@lists.xenproject.org, Julien Grall <jgrall@amazon.com>,
	Stefano Stabellini <sstabellini@kernel.org>, Wei Liu <wl@xen.org>,
	Julien Grall <julien@xen.org>
Subject: Re: [PATCH] CODING_STYLE: Add a section of the naming convention
Date: Wed, 6 Dec 2023 09:41:40 +0100	[thread overview]
Message-ID: <50b36423-d1e1-406f-a63f-66f2e4dce68e@suse.com> (raw)
In-Reply-To: <CA+zSX=aUV00BwnNfFTbCE=6PuVNT=UFvE0tnMO3UhwCMh5jmHQ@mail.gmail.com>

On 06.12.2023 03:21, George Dunlap wrote:
> On Tue, Dec 5, 2023 at 6:12 PM Julien Grall <julien@xen.org> 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>
>>
>> ---
>>     Changes in v2:
>>         - New wording
>>         - Update the section title
>>         - Add Jan's acked-by
>> ---
>>  CODING_STYLE | 9 +++++++++
>>  1 file changed, 9 insertions(+)
>>
>> diff --git a/CODING_STYLE b/CODING_STYLE
>> index ced3ade5a6fb..ed13ee2b664b 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 for files and command line options
>> +----------------------------------------------------
>> +
>> +'-' 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.
> 
> Sorry for not catching this last time; "are using X" isn't really
> idiomatic English; more idiomatic would be something like the
> following:
> 
> "Note that some existing options and file names use '_'.  This is now
> deprecated."
> 
> Since we're changing things, I *think* most style guides would advise
> against starting the sentence with a punctuation; so perhaps:
> 
> "Command-line options and file names should use '-' to separate words;
> e.g., timer-works."
> 
> And what about adding to the last paragraph:
> 
> "When touching code around command-line parameters still using '_', it
> is recommended to modify the documentation to say only '-', but modify
> the code to accept both '-' and '_' (for backwards compatibility)."

In this context see
https://lists.xen.org/archives/html/xen-devel/2020-01/msg01945.html
and Andrew's response
https://lists.xen.org/archives/html/xen-devel/2020-01/msg02006.html
I'm still in favor of addressing the issue centrally (making unnecessary
adjustments like you suggest in the new paragraph). Yet I think Andrew's
objection would cover such adjustments as much as my generic solution.

Jan