Designing command-line interfaces • Hacker News Board

Re: Designing command-line interfaces

#11

Post by scott_s » Fri, Aug 05, 2011, 5:48 PM UTC

mcantor wrote: post #7

Oh, and another: Use your language's command-line option processing libraries. OptionParser in ruby and argparse in python. There is no reason to eschew these libraries: they're part of the standard library, they require zero coupling to your app logic, and they handle all of the edge cases for free. "But I can just shift the arguments", you say! Yeah? Great! What if the user pipes input through STDOUT? What if the u…

And if you use C++ and are willing to use Boost, program_options: http://www.boost.org/doc/libs/1_47_0/doc/html/program_option...

I recognize that many people are not willing to use C++, and among those that are, many are still unwilling to use Boost, but I find the program_options library to be great. An example use that I think is reasonable and a big win over doing it myself: https://github.com/scotts/cellgen/blob/master/src/main.cpp#L...

Re: Designing command-line interfaces

#12

Post by mcantor » Fri, Aug 05, 2011, 5:57 PM UTC

One more:

Keep your "usage" blurb succinct and clear.

Don't clobber your users' terminals with two pages of output when they're not expecting it. If "yourapp", "yourapp -h" or "yourapp --invalid-flag" results in two screenfuls of information containing your app's license, installation instructions, contribution notes, an exhaustive listing of every single one of the 100 available subcommands, and a verbose representation of a configuration setting that 75% of your users won't care about, you're doing it wrong. (I'm looking at you, rvm).

This is similar to the idea of "You don't really understand something unless you can explain it so your grandmother gets it." Your app doesn't really have a sensible interface unless the top layer of its abstraction, or the most common commands, can be summarized in less than scrillions of lines of text. If you simply can't trim it down far enough, it's because you're breaking from the Unix philosophy and your utility is doing too much.

Re: Designing command-line interfaces

#13

Post by mcantor » Fri, Aug 05, 2011, 5:58 PM UTC

antoarts wrote: post #10

mcantor wrote: post #7

Oh, and another: Use your language's command-line option processing libraries. OptionParser in ruby and argparse in python. There is no reason to eschew these libraries: they're part of the standard library, they require zero coupling to your app logic, and they handle all of the edge cases for free. "But I can just shift the arguments", you say! Yeah? Great! What if the user pipes input through STDOUT? What if the u…

I choose not to discuss implementation in that article, but you should never reinvent the wheel (poorly).

I think a lot of people don't even realize such libraries are out there, or don't understand that there's a wheel being reinvented. ("It's just command line options. Why would you need a whole library to do that?")

Re: Designing command-line interfaces

#14

Post by technomancy » Fri, Aug 05, 2011, 6:12 PM UTC

huhtenberg wrote: post #5

(edit) There is a bit of terminology substitution going on in linked article. Command line interface is a shell. That's where one types the commands. Calling command options and arguments an interface may be technically correct, but it is not what is conventionally understood under a term of CLI . --- Speaking from an experience writing CLIs for configuration-heavy embedded devices, the key design element of a functi…

Command-line usability is at least 50% about tab completion.

Re: Designing command-line interfaces

#15

Post by Pewpewarrows » Fri, Aug 05, 2011, 6:20 PM UTC

One thing that always infuriates me:

If I go to --help or the man page for your command, and don't see a real example of how to use it immediately, you've failed me as a user.

Seeing your syntax tree and a list of every option and its description doesn't help me when I'm first trying to use your program. I just want to see one or two quick examples of real commands with a short sentence explaining each. After that I'll dive into the mess that is the dozens of flags and inputs to decipher exactly what I want.

Re: Designing command-line interfaces

#16

Post by pmr_ » Fri, Aug 05, 2011, 6:27 PM UTC

Pewpewarrows wrote: post #15

One thing that always infuriates me: If I go to --help or the man page for your command, and don't see a real example of how to use it immediately, you've failed me as a user. Seeing your syntax tree and a list of every option and its description doesn't help me when I'm first trying to use your program. I just want to see one or two quick examples of real commands with a short sentence explaining each. After that I'…

It always struck me as odd that man pages tend to have the EXAMPLES section as the last section of the document. I really would like it the other way around but this kinda fits with a bottom-up approach to learning. Look at the small details then get the full picture and how it's supposed to be used.

Re: Designing command-line interfaces

#17

Post by huhtenberg » Fri, Aug 05, 2011, 6:32 PM UTC

scott_s wrote: post #11

mcantor wrote: post #7

Oh, and another: Use your language's command-line option processing libraries. OptionParser in ruby and argparse in python. There is no reason to eschew these libraries: they're part of the standard library, they require zero coupling to your app logic, and they handle all of the edge cases for free. "But I can just shift the arguments", you say! Yeah? Great! What if the user pipes input through STDOUT? What if the u…

And if you use C++ and are willing to use Boost, program_options: http://www.boost.org/doc/libs/1_47_0/doc/html/program_option... I recognize that many people are not willing to use C++, and among those that are, many are still unwilling to use Boost, but I find the program_options library to be great. An example use that I think is reasonable and a big win over doing it myself: https://github.com/scotts/cellgen/blob…

> many are still* unwilling to use Boost*

I can appreciate the subtlety of wording, but in reality it is more of

> many will never be touching Boost even with a long pole and for a large sum of money

:)

Re: Designing command-line interfaces

#18

Post by zwp » Fri, Aug 05, 2011, 6:33 PM UTC

mcantor wrote: post #12

One more: Keep your "usage" blurb succinct and clear. Don't clobber your users' terminals with two pages of output when they're not expecting it. If "yourapp", "yourapp -h" or "yourapp --invalid-flag" results in two screenfuls of information containing your app's license, installation instructions, contribution notes, an exhaustive listing of every single one of the 100 available subcommands, and a verbose representa…

Also tedious:

    $ ls -Q
    ls: illegal option -- Q
    usage: ls -aAbBcCdeEfFghHiklLmnopqrRsStuUwxvV1@/[c | v]%[atime | crtime | ctime | mtime | all] [files]

It's succinct but that second line is almost completely useless.

Re: Designing command-line interfaces

#19

Post by alexis-d » Fri, Aug 05, 2011, 6:34 PM UTC

I agree with most of the article, except the yes/no part. In fact I think it's better to do :

"Do you want to do this (Y/n)?"

Where the most common option is uppercase so I can just hit enter.

Re: Designing command-line interfaces

#20

Post by there » Fri, Aug 05, 2011, 6:39 PM UTC

     Do you really want to do this (y/n)?

i would rather see this as

     Do you really want to do this (y/N)?

capitalize the option that will be used by default if you hit enter with no other input.