On 06.12.2023 03:21, George Dunlap wrote: > On Tue, Dec 5, 2023 at 6:12 PM Julien Grall <[email protected]> wrote: >> >> From: Julien Grall <[email protected]> >> >> 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 <[email protected]> >> >> --- >> 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
