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

From: Julien Grall <julien@xen.org>
To: Andrew Cooper <andrew.cooper3@citrix.com>,
	Jan Beulich <jbeulich@suse.com>,
	George Dunlap <george.dunlap@cloud.com>
Cc: xen-devel@lists.xenproject.org, Julien Grall <jgrall@amazon.com>,
	Stefano Stabellini <sstabellini@kernel.org>, Wei Liu <wl@xen.org>
Subject: Re: [PATCH] CODING_STYLE: Add a section of the naming convention
Date: Wed, 6 Dec 2023 11:22:07 +0000	[thread overview]
Message-ID: <33d82944-6c53-45c6-93d5-48d0be9257fd@xen.org> (raw)
In-Reply-To: <6f071eba-3995-451b-af80-efe875ec5ea8@citrix.com>

Hi,

On 06/12/2023 11:19, Andrew Cooper wrote:
> On 06/12/2023 8:41 am, Jan Beulich wrote:
>> 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.
> 
> Aliasing - and _ in the cmdline parsing breaks basic usability.
> 
> Its fine for new options to use -, and it's even fine-ish (but only if
> you're going to be the one doing security backports) to rename internal
> files.
> 
> But there is real and detrimental effect for altering the command line.
> 
> You will get people failing to express the option they intended when
> working with an older form of Xen.  You will need an absurd number of
> notes in the command line docs saying "newer versions of Xen accept an
> alias but you need to use the underscore form for backwards compatibility".
> 
> Not to mention that there are years of notes scattered all around the
> internet using the underscore forms, so it's likely that everyone will
> continue to use the underscore form, meaning that you don't even have a
> way to phase them out.
> 
> And for what?  An attempt to pretend that we don't have 2 decades of
> history where underscores where the norm?
> 
> It's tinkering, for no useful benefit and a clear cost.

+1 with what Andrew said.

Cheers,

-- 
Julien Grall