Description
Consider this content of concatentating transformer's Argument
's class:
Or this similar entry:
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:
-
Make the field name itself plural and
-
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