Coding Standards

This started out as issue #24 but even when that issue is (eventually) Closed, these notes will be important to maintain/improve coding:

---

Naming conventions

Functions and variables should have the following naming conventions applied consistently in dotfiles

• bash-completion functions begin with one underscore (e.g. _command completes for command)
• private functions and variables begin with two underscores (e.g. __prompt_git).
• variable names SHOULD be UPPERCASE
• use underscores_for_spaces in names, not minus-signs or KhamalCase
• group utility functions (not intended to be called interactively) by a namespace (e.g. __prompt)
• don't use Microsoft style is-a naming (e.g. fn_SomeFunction, STR_SOME_VARIABLE)

Shell coding standards

• in functions, use local variables in preference to "private" global ones, if possible
• always wrap variable references: ${SOME_VARIABLE}
• always quote expansions: "${@}", "${arr[@]}", "${*}"
• usually quote/wrap parameters: "{$1}" (fixes spaces in param values)
• use --long-switch-names for commands (e.g. GNU utilities), when they are available
• only interactive functions need and should have $FUNCDESC (see #23)

What's an "interactive" function, or a private function?

Interactive functions (and aliases) are intended to be called by someone from a command prompt or as part of some throw-away script. Private functions (and aliases) are to keep the code DRY or be a building-block for dotfiles itself, and are not generally useful otherwise.

There are cases where a building-block function also has interactive utility (e.g. path_add/path_remove, is_osx etc). Whether we should have a "private" __path_add and a public path_add alias for it is debatable.

Other general style/programming tips

• Defensive Bash Programming
• Bash-hackers:/syntax/Parameter Expansion
• Bash-hackers wiki (general tips/howto)

Polyglot issues

Generally this repository should be Shell script (Bash flavour). The source code language distribution is currently about this:

    Shell 66.1% Ruby 16.1% Lua 9.5% Perl 5.3% Python 2.7% CSS 0.3% 

So it is now mostly Shell, which is better than when I raised Issue #6

The script relies heavily on bash-isms. I had to put a guard in place to prevent errors when sourcing in POSIX mode (Issue #32).

The remaining dregg's of Ruby and Perl are located mainly in the scripts that live in the bin/ directory; inherited from Cowboy, and are not actually a concern since they are self-contained, not a part of the core workings of Dotfiles itself.

The Lua is all Hammerspoon configuration, not an issue.

The Python is a mixture of scripts in bin/ and some python helpers, also not an issue.