shellfu/notes/guidelines.md

Fastfoo guidelines

By Alois Mahdal

UI/UX

• Heavily prefer unix filter UI.

  If you can't do it with filtering, it could mean you should split your function anyway.

• Even function can use dash options and even usage().

• Do not think() in functions.

• Preferred capitalization in messages is:

  • all small for libs (debug/warn/die)

  • First cap for scripts

• Message width:

  • think/warn/die: try hard to never exceed 72

  • debug: do what you must

  • always try to split message to fixed part, colon and before colon and the "data" part after the colon, e.g.:

    file missing: /var/run/media/somebody/some-medium/some-long/path
    

    instead of:

    file /var/run/media/somebody/some-medium/some-long/path is missing
    

    (even if you think that it will be short)

API

Exit status

• consider using exit.sh

• do not use exit status to convey information other than success or error type

• use 1 for "no", 2 for syntax error (if applicable), more otherwise; note that shellfu pretty.die uses 9 as a generic status

Arguments

• Reserved options are

  • -q|--quiet, to turn off verbosity,
  • -v|--verbose, to turn on verbosity,
  • and -d|--debug to turn on debug output (stderr).

Variables

• module "bar" has implicitly reserved namespace "SHELLFU_BAR* and "__FOO_BAR*"

• few exceptions exist like SHELLFU_DEBUG, where Fastfoo itself reserves a module name

• always consider

  SHELLFU_BAR_BAZ=${SHELLFU_BAR_BAZ:-value}
  

  over

  SHELLFU_BAR_BAZ="value"
  

  since in the first case user can set this (in-line when calling your script or globally in .bashrc)

Principles

Be smart but honest

If you can default, default, otherwise be honest = fail.

Don't talk unless asked

Echo to stdout only if purpose of your script/function is to print that text. Otherwise use think() instead.

If you want to make your script "user-friendly" (like babbling about what it's doing), consider setting SHELLFU_VERBOSE to true in header of your script (and implementing -q|--quiet to tun it off).

Stop commenting

Don't use comments if you can make code readable enough.

Comments are good to explain special cases (like if something you can't fix is broken so you had to work around and now you know your code is stupid + ineffective but have to advise colleagues against fixing it). Sometimes they can be used for TODOs or for FIXMEs. Or if you really really tried hard but failed to write something in a readable manner (that's actually a FIXME).

But people use them also to "title" logical clusters of code (that don't make sense to separate to functions). Consider using think for that.

Go far to make code readable

Often if you can't think of a way to make the code nice, you might have other problem: your code is too complicated. Note that refactoring few lines away to a function call or using better (or some) naming convention can be a great help.