Need command style guide

[Greg Couch]

Would like to have guidance for outside developers on how to construct commands. The general command syntax is "name required-positional optional-positional keyword-value". There are techniques to make a required positional argument look like it's optional-- not good in general, but used for the atomspec argument of many commands. Likewise, there are ways of making the value for a keyword argument not needed. Guidance about when to to have subcommands instead of more options would useful. And guidance about how to document commands would also be helpful.

Initially assigning this to Elaine for a high level view. I expect that the programmers will add examples.

[Elaine Meng]

Considering I didn’t even know that that was the structure, I think Greg and/or Conrad should simply add that sentence to the bundle instructions and example(s).

I don’t have a a generic mental rule (or any idea of how to state it) as to when one needs subcommands rather than options, however. As far as I can tell it is a case-dependent judgment, but maybe the rest of the team has a more definite rule. My only generic pronouncements:

• if there is an existing similar command, options should be as analogous as possible, or even the same (e.g. “log true” “save filename|browse")
• don’t make the user repeatedly enter long commands for common operations (judicious use of defaults and whether un-named options remain unchanged from current)
• defaults should be what is expected to be most common
• avoid sub-sub commands if at all possible

Feel free to put that in the programming documentation if there is a suitable place. However, these are all pretty obvious and almost should go without saying.

[Elaine Meng]

Collated suggestions of what is supposed to be in this page. I don't know the answers to some of these and even my statements below might be wrong, so somebody else needs to write at least the initial draft. Probably should be a page somewhere in the Programmer Guide, linked to the bundle-making instructions.

(1) [from Greg's initial ticket] The general command syntax is "name required-positional optional-positional keyword-value". There are techniques to make a required positional argument look like it's optional -- not good in general, but used for the atomspec argument of many commands. Likewise, there are ways of making the value for a keyword argument not needed.

(1a) atomspec/modelspec is generally before other options, but many commands allow it to be blank to mean "all"

(2) When to to have subcommands instead of more options in the top-level command?

(3) When are single keywords allowed as opposed to keyword-value pairs? Are the latter always encouraged over the former?

(4) Option keywords are camelCaps if compound words, and should not contain underscores or other special characters

(5) How to document commands? I guess this means so that their "usage" info is reasonable, or maybe also the full user documentation if not part of the standard downloaded commands.

[Elaine Meng]

Collated suggestions of what is supposed to be in this page. I don't know the answers to some of these and even my statements below might be wrong, so somebody else needs to write at least the initial draft. Probably should be a page somewhere in the Programmer Guide, linked to the bundle-making instructions.

(1) [from Greg's initial ticket] The general command syntax is "name required-positional optional-positional keyword-value". There are techniques to make a required positional argument look like it's optional -- not good in general, but used for the atomspec argument of many commands. Likewise, there are ways of making the value for a keyword argument not needed.

(1a) atomspec/modelspec is generally before other options, but many commands allow it to be blank to mean "all"

(2) When to to have subcommands instead of more options in the top-level command?

(2a) Avoid sub-subcommands if at all possible

(3) When are single keywords allowed as opposed to keyword-value pairs? Are the latter always encouraged over the former?

(4) Option keywords are camelCaps if compound words, and should not contain underscores or other special characters

(5) How to document commands? I guess this means so that their "usage" info is reasonable, or maybe also the full user documentation if not part of the standard downloaded commands.

(6) if there is an existing similar command or analogous option, keywords should be analogous, or if appropriate, the same (e.g. “log true” “save filename|browse")

(7) don’t make the user repeatedly enter long commands for common operations (judicious use of defaults and whether un-named options remain unchanged from current)

(8) defaults should be what is expected to be most common

[Eric Pettersen]

The document should probably also discuss the rare-ish case of commands that require more than one atom spec.

[Eric Pettersen]

Placed the style guide into the docs and linked to it in various places. Will mention it on chimera-users once it's on the web site.