torus-cli
torus-cli copied to clipboard
Style guide - Successful, failure, error states
Talking points
- Complex error messages
- Error message plus description
- Successful states contain output or not?
- In a lot of system tools no output is the success state
- Most of our commands now provide a confirmation message
- Invalid usage? validation failure?
We should always lead a complex error message with a sane/friendly explanation, followed by the more technical output (which can be helpful to power users, and useful in debugging).
We should never panic, that's a bug.
In a lot of cases our command output infer context from their cwd. Because of this I feel that every command should have a success or failure message that shows the result of this. For instance, showing the path that has been computed, or showing which object has been created. We're much more of a product that just a command line utility, so I don't think that it's too unexpected.
+1 to utilizing context where possible.
I'm in favor of having success states contain output but I'm coming at this from a non-programmer background. Are success messages considered extraneous to the average programmer? Confirmation seems more considered.
Another topic we talked about was empty states.
I think we should utilize the hints ui in our empty states to suggest the user can perform an action in order to make the state non-empty. Example:
$ torus services list
Project 'www' has no services.
* Create a new service by running 'torus services create'