Style guide

[jeffandersen]

To reduce fragmentation in our CLI and to improve some of the interactions we use, we are going to produce a style guide.

This issue will act as a central hub for all things style guide, which will start with discussion around each major area of input/output.

• Tables and lists
• Success, failure, and error states
• Whitespace and layout
• Input prompts
• Rich formatting

[jeffandersen]

We can use this issue to talk a bit about our philosophy and approach to general layout of the tool.

Talking points

• Args vs options vs flag
• Hierarchy of commands (nested vs top level)
• Naming
  • Tense, plurality, etc

[ntassone]

Some inspiration and resources:

• Our own @jeffandersen's Designing for CLI post
• Heroku CLI Style Guide
• Angular style guide has an interesting format with notes for Do, Consider, Avoid etc
• IEEE Standards guide
• A thing from a computer science thing

[ntassone]

We had a good discussion about this IRL last week. Didn't get into specifics as much as general philosophy but a good kick off for discussion.

To start the discussion here, I'll make some reaches as to how I think the points above should be addressed and go from there:

Args vs options vs flag

Arguments are passed into options so that doesn't really warrant much discussion, I'll just talk about options for the time being.

These are currently being referred to in the documentation as both options and flags. In the code they're referred to as flags (for the most part). To keep it consistent and for simplicity's sake, we should call them options when referring to both global/command options.

Options should be in the format of two dashes with one phrase after: --option. In the case of a multi word phrase, words should be separated by a dash: --multi-word. Each option should contain a sensible lowercase, one character, shortcut version like -o for --option.

[ntassone]

Command Naming/Describing

The general guide to naming a command should be to make it as simple and relevant as possible. When writing a description of the command for help, or in a hint (!), I think we add to the style guide that being concise is key. We have documentation where you can expand and explain more verbosely.

Tense

Should consistently be in Future I Simple – basically will without actually saying will. torus profile will Manage your Torus account. Don't restate the command. Example:

Correct

• torus profile: Manage your Torus account
• torus send: Send an invitation to join an organization to an email address

Incorrect

• torus profile: Profile manages your Torus account (restates and wrong tense)
• torus send: Sent and invite to join (wrong tense)

Plurals

I don't think we can assign too many rules to plurality. As long as you are consistent, plurality will change on a case by case basis.

For example, it makes sense for torus invites to be plural because invite would infer a verb, like torus invite <user>. However, the help for invites mixes the words invites with invitations when describing invitations. Using invitations in the descriptive text and only using invites when referring to the command would help make the help more clear.