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

[George Dunlap <george.dunlap@xxxxxxxxx>]

On Wed, Dec 6, 2023 at 11:22 AM Julien Grall <julien@xxxxxxx> wrote:
>
> 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@xxxxxxx> wrote:
> >>>> From: Julien Grall <jgrall@xxxxxxxxxx>
> >>>>
> >>>> 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@xxxxxxxxxx>
> >>>>
> >>>> ---
> >>>>      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.

Haven't given it full thought, because I absolutely did not want to
make this change take longer to get in. :-). The existence of
disagreement is enough for me to withdraw my suggestion.

 -George