Skip to content

Pluralize names of settings/arguments field values to plural when array #2040

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Closed
TomFinley opened this issue Jan 6, 2019 · 0 comments
Closed
Assignees
Labels
API Issues pertaining the friendly API

Comments

@TomFinley
Copy link
Contributor

TomFinley commented Jan 6, 2019

Consider this content of concatentating transformer's Argument's class:

[Argument(ArgumentType.Multiple | ArgumentType.Required, HelpText = "New column definition(s) (optional form: name:srcs)", ShortName = "col", SortOrder = 1)]
public Column[] Column;

Or this similar entry:

[Argument(ArgumentType.Multiple, HelpText = "New column definition(s) (optional form: name:srcs)", ShortName = "col", SortOrder = 1)]
public TaggedColumn[] Column;

You will notice something curious. This is an array of Column[], yet is named Column, not Columns. The reason for this is somewhat odd: this settings object originally arose out of the need to provide a command line settable object back when this code was supporting a tool (and not an API!). And, the presence of an array indicate that this setting can be set multiple times... so one could say, for instance, column=Foo column=Bar column=Biz, and so wind up with this field populated with 3 items. In this setting the name "column" is the most natural name.

Now we are trying to ship an API. What we did for the convenience of the command line now causes confusion for an API user, because they see an array (which can clearly handle multiple items), yet it has a singular name!

Fortunately, we can have our cake and eat it too: the ArgumentAttribute has something called Name, to allow the field name to be distinguished from the command line name. So, this:

[Argument(ArgumentType.Multiple | ArgumentType.Required,
    HelpText = "New column definition(s) (optional form: name:srcs)",
    ShortName = "col", SortOrder = 1)]
public Column[] Column;

could become this:

[Argument(ArgumentType.Multiple | ArgumentType.Required,
    HelpText = "New column definition(s) (optional form: name:srcs)",
    Name = "Column", ShortName = "col", SortOrder = 1)]
public Column[] Columns;

and remain equivalent from the command line perspective, while not being confusing from the API perspective.

As a general rule any field with an ArgumentAttribute attribute on it that is also an array, we have often not made plural, for the aforementioned reasons. If it is singular:

  1. Make the field name itself plural and

  2. Retain the old singular command line as this Name parameter, so as to retain the benefit of why we named it this way in the first place.

However, please, not thoughtlessly! Think about whether that change makes sense in context.

/cc @stephentoub

@TomFinley TomFinley added the API Issues pertaining the friendly API label Jan 6, 2019
@najeeb-kazmi najeeb-kazmi self-assigned this Jan 10, 2019
@ghost ghost locked as resolved and limited conversation to collaborators Mar 25, 2022
Sign up for free to subscribe to this conversation on GitHub. Already have an account? Sign in.
Labels
API Issues pertaining the friendly API
Projects
None yet
Development

No branches or pull requests

2 participants