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

[George Dunlap <george.dunlap@xxxxxxxxx>]

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)."

I was going to say I'm happy to change on check-in, but I think with
three changes it's probably worth waiting for a fuller discussion.

 -George