[mcantor]

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.

[zwp]

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.

[mcantor]

One of my favorites is tar:

    $ tar -m foo
    tar: You must specify one of the `-Acdtrux' options
    Try `tar --help' or `tar --usage' for more information.

Oh, right! `-Acdtrux'! How could I have forgotten. I deal with ACD Trucks all the time. (?!?!)

[ilikepi]

Speaking of "usage" blurbs, for $DIETY's sake, please assume 80-character wide terminals.

[janus]

Also I'm looking at you, rails.