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

From: George Dunlap <george.dunlap@cloud.com>
To: Julien Grall <julien@xen.org>
Cc: xen-devel@lists.xenproject.org, Julien Grall <jgrall@amazon.com>,
	 Andrew Cooper <andrew.cooper3@citrix.com>,
	Jan Beulich <jbeulich@suse.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 02:21:07 +0000	[thread overview]
Message-ID: <CA+zSX=aUV00BwnNfFTbCE=6PuVNT=UFvE0tnMO3UhwCMh5jmHQ@mail.gmail.com> (raw)
In-Reply-To: <20231205181218.74667-1-julien@xen.org>

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

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