diff options
Diffstat (limited to 'HACKING/code-quality.md')
| -rw-r--r-- | HACKING/code-quality.md | 25 |
1 files changed, 12 insertions, 13 deletions
diff --git a/HACKING/code-quality.md b/HACKING/code-quality.md index 8efd561..f296621 100644 --- a/HACKING/code-quality.md +++ b/HACKING/code-quality.md @@ -1,7 +1,7 @@ Code content ============ -Be aware of the `librelib(7)` library suite, which lives `src/lib`. +Be aware of the `librelib(7)` library suite, which lives in `src/lib`. It is a suite of Bash libraries that will help you out. Most of the people looking at the libretools code are familiar with the `messages` part of it, which actually contains a bunch of utility routines, not @@ -16,14 +16,13 @@ Message printing: All of the message printing routines, except for of that; don't use string interpolation (don't do `"foo ${var} bar"`). The reason for this is that if you don't do string interpolation, messages can be automatically internationalized. -(Internationalization is incomplete at the momement) Message printing: The in `--help`/`-h` text, use `print` to print lines that should not wrap, `echo` to print blank lines, `prose` to print paragraphs, `bullet` to print bullet points, and `flag` to print option flags. The text should follow this general format: - print "Usage: %s [OPTIONS] VARS_ARE_UNDERSCORE_AND_CAPITAL" "${program_name}" + print "Usage: %s [OPTIONS] VARS_ARE_UNDERSCORE_AND_CAPITAL" "${program_name}" print "One line description of program, no period" echo prose "More details. This is a paragraph." @@ -34,10 +33,6 @@ option flags. The text should follow this general format: In the "Usage:" line, use printf `%s` and the value `"${0##*/}"` to determine the program name at runtime. -There used to be guidelines for how to align the option flags and -descriptions, but now the `flag` command exists takes care of it for -you. Yay for things being easier! - When using `set -u`, `set -e`, or `trap`, you should also use `set -E` to have the error handling be passed down to subshells. @@ -54,6 +49,9 @@ Use `set -u` if you can; it makes using an unset variable an error. - The reason for this is that a normal string variable is basically an array with length=1; an unset variable looks like an array with length=0. Weird stuff. + - Actually, that was only true in Bash <4.4; but since the change + wasn't mentioned in the NEWS, I suspect that a subsequent version + will revert to the pre-4.4 behavior. In the shebang, use `#!/usr/bin/env bash`. This allows us to not hardcode the location of bash (I'm not sure why this is useful for @@ -62,8 +60,8 @@ use-case for it). In the shebang, don't pass flags to bash, besides breaking `env` (above), it means people will make mistakes when debugging, and -running things with `bash FILENAME`. Instead, use `set` to adjust the -flags inside of the program. +running things with `bash -x FILENAME`. Instead, use `set` to adjust +the flags inside of the program. Obey `$TMPDIR`. It's usually as easy as passing `--tmpdir` to `mktemp`. @@ -81,12 +79,13 @@ A lot of people look at the "Advanced Bash Scripting" ebook--DO NOT do that, it is trash... though it contains a "reference card" page that may be useful and isn't trash. -Take a look at Gentoo's Bash guidelines +Take a look at Gentoo's Bash +guidelines <http://devmanual.gentoo.org/tools-reference/bash/index.html>. They're pretty good, and cover most of the "gotcha's" about Bash -syntax. It mentions but discourages the use of Bash 3 -features... why? Who still uses Bash 2? Feel free to use Bash 4 -features! +syntax. Though, it mentions but discourages the use of Bash 3 +features... why? Who still uses Bash 2? For libretools, you should +feel free to use Bash 4 features! I wrote an article on Bash arrays <https://lukeshu.com/blog/bash-arrays.html>. A lot of people think |