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 ###

*   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 ffoo core.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 "FFOO_BAR* and "__FOO_BAR*"

*   few exceptions exist like FFOO_DEBUG, where Fastfoo itself reserves
    a module name

*   always consider

        FFOO_BAR_BAZ=${abc:-value}

    over

        FFOO_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 ###

Use echo only if purpose of your script/function **is** to print.
Otherwise use `think()` instead.

If you want to make your script "user-friendly" (like babbling about
what it's doing, consider setting `FFOO_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.