Writing Consistent Tools (2019)

https://www.netmeister.org/blog/consistent-tools.html

by teleforce • 5 years ago

46 5 5 years ago

klodolph• 5 years ago

I think it also helps to think about what the consumer of your tools is, and how often the command-line needs to be written.

Is it a tool like Git, that you run over and over again, many times throughout the day?

Or is it something like 'find', where you run it every once in a while, but aren’t used to using it?

Or is it something like 'ld', where you only ever run it from your build system?

Tools like Git it's nice to have options like -p for --patch.

Tools you only use from build scripts—easy enough to only give them long options. You don't need short options, mostly. Same goes for tools that are only written seldom. You won’t remember what the short options mean, for a tool that you run once or twice a month, so you’re just shooting yourself in the foot by using them.

yagizdegirmenci• 5 years ago

-j -- generate output in JSON format (if applicable)

The standard is -o --output flag for specifying a different format than plan plain text.

I think that one important thing about writing consistent and powerful tools is having clear and remindable subcommands and flags, i feel like i'm writing a narrative when i'm working with Vault and AWS CLI, they are incredibly well designed.

formerly_proven• 5 years ago

If the tool's main purpose is generating some specific file, then -o/--output should name that file or directory.

If the tool generates some table-like output, then -o/--output usually allows changing what exactly is output. E.g. lsblk -o +model.

For different output formats I've seen -f/--format {text,json,xml}, might be a bit verbose. --json is probably fine. Short version needed? Probably not.

petepete• 5 years ago

I prefer long options purely because the short ones vary so much program by program. With a shell that provides nice autocompletion there's barely any more typing involved and your history is easier to search through.

nirushiv• 5 years ago

Not a fan of overloading V for both version and verbose. Since starting to write Go / working in the industry, unabbreviated flag names have really grown on me.

Writing Consistent Tools (2019)

Related Stories