From 59ab5f0d42872e08cbd721321a3f526c395b9d14 Mon Sep 17 00:00:00 2001 From: Luke Shumaker Date: Wed, 24 May 2017 13:16:59 -0400 Subject: Tidy the HACKING documentation. --- HACKING/code-quality.md | 25 ++++++++++++------------- HACKING/code-style.md | 2 +- HACKING/contributing.md | 2 +- 3 files changed, 14 insertions(+), 15 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 . 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 . A lot of people think diff --git a/HACKING/code-style.md b/HACKING/code-style.md index 077bc49..601ead1 100644 --- a/HACKING/code-style.md +++ b/HACKING/code-style.md @@ -35,7 +35,7 @@ should be Of course, if the upper bound is a variable, the C-like syntax is the better option, as otherwise you would have to use `seq` (calling -an external), or `eval` (gross, easy to mess up royally). +an external), or `eval` (gross, easy to mess up). Indent comments like you would code; don't leave them at the beginning of the line. Example: diff --git a/HACKING/contributing.md b/HACKING/contributing.md index 65066b5..3a9d083 100644 --- a/HACKING/contributing.md +++ b/HACKING/contributing.md @@ -5,7 +5,7 @@ I'd love to have your patches! Code should be hackable; if you want to modify something, but can't figure out how: 1) ping me for help, 2) it probably means the code was too complicated in the first place. -Patches should be sent to ; please put +Patches should be sent to ; please put "[PATCH]" and "libretools" in the subject line. If you have commit access, but want me to look over it first, feel free to create a new branch in git, and I will notice it. Try to avoid pushing to the -- cgit v1.2.2