docs(styleguide): add section for quoting

- docs(styleguide): fix example for case patterns
- docs(styleguide): rephrase note on quoting of here strings
- docs(styleguide): fix explanation of _comp_split
- docs(styleguide): elaborate description of quoting
- docs(styleguide): update examples of quoting

Co-authored-by: Ville Skyttä <ville.skytta@iki.fi>

Author: akinomyoga

doc/styleguide.md

@@ -122,3 +122,62 @@ it.
 ## Function and variable names
 
 See [API and naming](api-and-naming.md).
+
+## Quoting of words
+
+To avoid unexpected word splitting and pathname expansions, an argument of
+commands needs to be properly quoted when it contains shell expansions such as
+`$var`, `$(cmd)`, and `$((expr))`.
+
+When one intentionally wants word splitting and pathname expansions, one should
+consider using the utility functions provided by bash-completion.  To safely
+split a string without being affected by non-standard `IFS` and pathname
+expansions, use the shell function `_comp_split`.  To safely obtain filenames
+by pathname expansions without being affected by `failglob`, etc., use the
+shell function `_comp_expand_glob`.  Note that `_comp_expand_glob` should be
+always used for the pathname patterns even if the pattern does not contain
+shell expansions.
+
+In the following contexts, the quoting to suppress word splitting and pathname
+expansions are not needed.
+
+- The right-hand sides of variable assignments ... `v=WORD` (e.g. `v=$var`)
+- The arguments of conditional commands ... `[[ WORD ]]` (e.g. `[[ $var ]]`)
+- The argument specified to `case` statement ... `case WORD in foo) ;; esac`
+  (e.g. `case $var in foo) ;; esac`)
+
+In bash-completion, we do not quote them by default.  However, there are
+exceptions where the quoting is still needed for other reasons.
+
+- When the word *directly* contains shell special characters (space, tab,
+  newline, or a character from ``;|&()<>\\$`'"#!~{``), these characters need to
+  be quoted.  The "*directly*" means that the special characters produced by
+  shell expansions are excluded here.  For example, when one wants to include a
+  whitespace as a part of the value of the word, the right-hand side can be
+  quoted as `v="a b"`.
+- An empty word (i.e., the word whose value is an empty string) is specified by
+  `""`.  The right-hand side of an assignment technically can be an empty
+  string as `var=`, but we still use `var=""` there because `shellcheck`
+  suggests that e.g. `var= cmd` is confusing with `var=cmd`.
+- `$*` and `${array[*]}` need to be always quoted because they can be affected
+  by the word splitting in bash <= 4.2 even in the above contexts.
+- In the following contexts, double-quoting of shell expansions is needed
+  unless the result of expansions is intentionally treated as glob patterns or
+  regular expressions.
+  - The right-hand sides of `==`, `!=`, and `=~` in the conditional commands
+    ... `[[ word == "$var" ]]`
+  - The case patterns ... `case word in "$var") ;; esac`
+
+Note: Here strings `cat <<<$var` are also supposed to be safe against word
+splitting and pathname expansions without quoting, but bash <= 4.3 has a bug
+[1], so they need to be quoted for as long as we support bash 4.3.
+
+- [koalaman/shellcheck#1009 (comment)](https://github.com/koalaman/shellcheck/issues/1009#issuecomment-488395630)
+
+There are also preferences on the type of quoting, which are though not too
+strict.  We prefer to use double quotes over single quotes by default.  When
+the value contains `$`, `` ` ``, `\`, and `"`, we can use single quotes to
+avoid backslash escaping or use the one that minimizes the use of backslash
+escaping.  When the value contains control characters such as a tab and a
+newline, we do not directly include them but we use backslash escape sequences
+such as `\t` and `\n` in the escape string `$'...'`.