Candidates for renaming before v3

[epage]

Issue by pksunkara
Saturday Oct 10, 2020 at 15:18 GMT
Originally opened as clap-rs/clap#2164

---

• AppSettings
  • ArgsNegateSubcommands -> ?
  • GlobalVersion -> PropagateVersion
  • HelpRequired -> RequireHelp
  • SubcommandRequired -> RequireSubcommand
  • ArgRequiredElseHelp -> DisplayHelpWhenNoArg
  • SubcommandRequiredElseHelp -> DisplayHelpWhenNoSubcommand
  • AllowLeadingHyphen -> AllowHyphenValues (did this in Arg already)
  • SubcommandPrecedenceOverArg -> GiveSubcommandPrecedenceOverArg
  • SubcommandsNegateReqs -> ?
  • UnifiedHelpMessage -> UnifyHelpMessage
  • ColoredHelp -> ColorHelp / UseColoredHelp / ?
  • TrailingVarArg -> ?
• Make App::generate_usage (a new function) consistent with App::render_* (also new)

[epage]

Comment by epage
Thursday Jul 22, 2021 at 14:48 GMT

---

RE GlobalVersion

A benefit to this name is clap already has the term "global" that I think translates to this.

RE RequireHelp and RequireSubcommand

The thing I dislike here is that one "requires" is for developers and the other is for users. It'd be nice if we had a way of distinguishing these.

Maybe RequireHelp should be ExpectHelp like Option::expect?

This should also probably be renamed to ExpectAbout because the help argument was renamed to about.

RE ArgRequiredElseHelp

I like the consistency in using Require. Maybe RequireArgElseHelp

[epage]

Comment by epage
Thursday Jul 22, 2021 at 15:01 GMT

---

So my current table

• ArgsNegateSubcommands
• GlobalVersion
• HelpRequired -> ExpectAbout
• SubcommandRequired -> RequireSubcommand
• SubcommandRequiredElseHelp -> RequireSubcommandElseHelp
• ArgRequiredElseHelp -> RequireArgElseHelp
• AllowLeadingHyphen: rename the Arg version back. This is more accurate than "Hyphen values" in my mind
• SubcommandPrecedenceOverArg
• SubcmmandsNegateReqs -> SubcommandNegateRequires
• ColoredHelp -> ColorHelp
• AllArgsOverrideSelf -> ArgsOverrideSelf (all is redundant, this is set on the app)
• UnifiedHelpMessage -> UnifyHelpMessage

[epage]

Comment by kbknapp
Saturday Oct 02, 2021 at 00:10 GMT

---

My general thoughts are, "What is least surprising or what is most likely to be searched for in the docs when wanting capability X." With a strong preference for consistency (back to my least surprising point) over perfect naming. So if we are using a verb/noun in some context, once the user has internalized that meaning with regard for clap, seeing that same verb or noun should have the same result.

I tend to think in terms of Noun_Verb(Past Participle)[_Context If Needed] when it's an attribute applied to an item, or [Verb_Noun] when it's instruction for clap to perform an action. There are several instances where this ins't the case, and those are ones I'd lean to towards changing, if any.

It could be argued that we should have different structure based on if the action is at parser build time, parse time, or validation time...as well as if it's a setting for clap, the developer, or the end user. But naming is one of the most bike-shedable things in CS so I'm partial to just leave well enough alone.

Likewise I tend to think that unless a name is actively causing a problem, or conflicting with some other naming scheme we've been using it's a low priority for change. Churn is more detrimental to downstream users than a less than perfect name.

Just my 2 cents.

[epage]

Comment by epage
Saturday Oct 02, 2021 at 18:18 GMT

---

My general thoughts are, "What is least surprising or what is most likely to be searched for in the docs when wanting capability X." With a strong preference for consistency (back to my least surprising point) over perfect naming. So if we are using a verb/noun in some context, once the user has internalized that meaning with regard for clap, seeing that same verb or noun should have the same result.

Another consideration for having a good scheme and having the feature stand out by being first (usually a noun) is it makes it easier to scan and discover new features when dealing with a specific domain (e.g. its easy to find Settings related to subcommands when they start with Subcommand)

Likewise I tend to think that unless a name is actively causing a problem, or conflicting with some other naming scheme we've been using it's a low priority for change. Churn is more detrimental to downstream users than a less than perfect name.

I've been impacted by both sides of this. Churn is rough. Similarly, inconsistent and undiscoverable names are also rough. I recently ran into this with nom where I didn't know features existed and did things in very round about ways because the naming was bad, inconsistent, and the docs didn't help towards discoverablity (I've been creating issues and prepping PRs to help improve this)

---

For v3, probably my biggest care about is if we started some renames and, if so, is it in a polished enough state or should we change it one way or the other. Anything else I can see pushing off to a later release. I guess I'd also throw in "having an API style guide" so new features are more likely to be right from the beginning.

[epage]

Comment by epage
Monday Oct 04, 2021 at 16:43 GMT

---

One rename we should do for v3 is make App::generate_usage (a new function) consistent with App::render_* (also new)

[epage]

Comment by epage
Saturday Oct 16, 2021 at 21:04 GMT

---

Based on kbknapp's post, I recommend we wrap this up with the following renames:

• HelpRequired -> AboutExpected: using the .expect verbiage to distance this from the word "require" which has a strong runtime connotation to users and we've rena med Arg::help to Arg::about (which personally I dislike because I prefer the naming consistency than perfect accuracy for finding this in docs)
• AllowLeadingHyphen: rename the Arg version back to this. This is more accurate than "Hyphen values" in my mind
• SubcmmandsNegateReqs -> SubcommandNegateRequires
• AllArgsOverrideSelf -> ArgsOverrideSelf (all is redundant, this is set on the app)
• mut_arg -> arg_mut (_mut should be a suffix), new this release

If I were to prioritize this, I would say

• AllowLeadingHyphen: rename the Arg version back to this. This is more accurate than "Hyphen values" in my mind and is the less disruptive route for clap2 users
• mut_arg -> arg_mut (_mut should be a suffix, we should clarify this is a get and not set), new this release

If we keep with NounVerb, there are other renames we can do to be more consistent with that but people have already been living with it, they can live with it a little longer.

I did not see any other renames that I would undo because of the background / preference towards Setting::NounVerb

[epage]

Comment by epage
Wednesday Nov 03, 2021 at 02:04 GMT

---

Another thought on AllowLeadingHyphen vs AllowHyphenValues is clap-rs/clap#1210 which, in the discussion, includes supporting alternative argument sigils, like Windows style /. I've not dug into the code to confirm this but I wonder if we can take inspiration from SubcommandPrecedenceOverArg on the naming, like ValuePrecedenceOverArg