Skip to content

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

Closed
@TomFinley

Description

@TomFinley

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

Metadata

Metadata

Assignees

Labels

APIIssues pertaining the friendly API

Type

No type

Projects

No projects

Milestone

No milestone

Relationships

None yet

Development

No branches or pull requests

Issue actions