1- = Coding Style Guide
1+ # Coding Style Guide
22
3- == Introduction
3+ ## Introduction
44
55This document attempts to explain the basic styles and patterns that
6- are used in the bash completion. New code should try to conform to
6+ are used in the bash completion. New code should try to conform to
77these standards so that it is as easy to maintain as existing code.
88Of course every rule has an exception, but it's important to know
99the rules nonetheless!
@@ -13,103 +13,107 @@ codebase, who are in the process of getting their code reviewed.
1313Before getting a review, please read over this document and make
1414sure your code conforms to the recommendations here.
1515
16- == Indentation
16+ ## Indentation
1717
1818Indent step should be 4 spaces, no tabs.
1919
20- == Globbing in case labels
20+ ## Globbing in case labels
2121
2222Avoid "fancy" globbing in case labels, just use traditional style when
23- possible. For example, do " --foo|--bar)" instead of " --@(foo|bar))" .
23+ possible. For example, do ` --foo|--bar) ` instead of ` --@(foo|bar)) ` .
2424Rationale: the former is easier to read, often easier to grep, and
2525doesn't confuse editors as bad as the latter, and is concise enough.
2626
27- == [[ ]] vs [ ]
27+ ## ` [[ ]]` vs ` [ ] `
2828
29- Always use [[ ]] instead of [ ]. Rationale: the former is less error
29+ Always use ` [[ ]] ` instead of ` [ ] ` . Rationale: the former is less error
3030prone, more featureful, and slightly faster.
3131
32- == Line wrapping
32+ ## Line wrapping
3333
3434Try to wrap lines at 79 characters. Never go past this limit, unless
3535you absolutely need to (example: a long sed regular expression, or the
3636like). This also holds true for the documentation and the testsuite.
3737Other files, like ChangeLog, or COPYING, are exempt from this rule.
3838
39- == $(...) vs \`...`
39+ ## ` $( ) ` vs backticks
4040
4141When you need to do some code substitution in your completion script,
42- you *MUST* use the $(...) construct, rather than the \`...` . The former
42+ you _ MUST _ use the ` $(...) ` construct, rather than backticks . The former
4343is preferable because anyone, with any keyboard layout, is able to
4444type it. Backticks aren't always available, without doing strange
4545key combinations.
4646
47- == -o filenames
47+ ## ` -o filenames `
4848
49- As a rule of thumb, do not use " complete -o filenames" . Doing it makes
49+ As a rule of thumb, do not use ` complete -o filenames ` . Doing it makes
5050it take effect for all completions from the affected function, which
5151may break things if some completions from the function must not be
52- escaped as filenames. Instead, use " compopt -o filenames" to turn on
53- " -o filenames" behavior dynamically when returning completions that
52+ escaped as filenames. Instead, use ` compopt -o filenames ` to turn on
53+ ` -o filenames ` behavior dynamically when returning completions that
5454need that kind of processing (e.g. file and command names). The
55- _filedir and _filedir_xspec helpers do this automatically whenever
55+ ` _filedir ` and ` _filedir_xspec ` helpers do this automatically whenever
5656they return some completions.
5757
58- == `[[ ${COMPREPLY-} == *= ]] && compopt -o nospace`
58+ ## ` [[ ${COMPREPLY-} == *= ]] && compopt -o nospace `
5959
6060The above is functionally a shorthand for:
6161
62- if [[ ${#COMPREPLY[@]} -eq 1 && ${COMPREPLY[0]} == *= ]]; then
63- compopt -o nospace
64- fi
62+ ``` bash
63+ if [[ ${# COMPREPLY[@]} -eq 1 && ${COMPREPLY[0]} == * = ]]; then
64+ compopt -o nospace
65+ fi
66+ ```
6567
6668It is used to ensure that long options' name won't get a space
67- appended after the equal sign. Calling compopt -o nospace makes sense
69+ appended after the equal sign. Calling ` compopt -o nospace ` makes sense
6870in case completion actually occurs: when only one completion is
69- available in COMPREPLY.
71+ available in ` COMPREPLY ` .
7072
71- == `$split && return`
73+ ## ` $split && return `
7274
73- Should be used in completions using the -s flag of _init_completion,
74- or other similar cases where _split_longopt has been invoked, after
75- $prev has been managed but before $cur is considered. If $cur of the
76- form --foo=bar was split into $ prev=--foo and $ cur=bar and the $prev
77- block did not process the option argument completion, it makes sense
78- to return immediately after the $prev block because --foo obviously
75+ Should be used in completions using the ` -s ` flag of ` _init_completion ` ,
76+ or other similar cases where ` _split_longopt ` has been invoked, after
77+ ` $prev ` has been managed but before ` $cur ` is considered. If ` $cur ` of the
78+ form ` --foo=bar ` was split into ` prev=--foo ` and ` cur=bar ` , and the ` $prev `
79+ block did not process the option argument completion, it makes sense to return
80+ immediately after the $prev block because` --foo ` obviously
7981takes an argument and the remainder of the completion function is
8082unlikely to provide meaningful results for the required argument.
8183Think of this as a catch-all for unknown options requiring an
8284argument.
8385
8486Note that even when using this, options that are known to require an
8587argument but for which we don't have argument completion should be
86- explicitly handled (non-completed) in the $prev handling block because
87- --foo=bar options can often be written without the equals sign, and in
88+ explicitly handled (non-completed) in the ` $prev ` handling block because
89+ ` --foo=bar ` options can often be written without the equals sign, and in
8890that case the long option splitting does not occur.
8991
90- == Use arithmetic evaluation
92+ ## Use arithmetic evaluation
9193
9294When dealing with numeric data, take advantage of arithmetic evaluation.
93- In essence, use (( ... )) whenever it can replace [[ ... ]] because the
94- syntax is more readable; no need for $ -prefixes, numeric comparison etc
95+ In essence, use ` (( ... )) ` whenever it can replace ` [[ ... ]] ` because the
96+ syntax is more readable; no need for ` $ ` -prefixes, numeric comparison etc
9597operators are more familiar and easier on the eye.
9698
97- == Array subscript access
99+ ## Array subscript access
98100
99101Array subscripts are arithmetic expressions, take advantage of that.
100- E.g. write ${foo[bar]}, not ${foo[$bar]}, and similarly ${foo[bar+1]}
101- vs ${foo[((bar+1))]} or ${foo[$((bar+1))]}, ${foo[--i]} vs ${foo[((--i))]}.
102+ E.g. write ` ${foo[bar]} ` , not ` ${foo[$bar]} ` , and similarly ` ${foo[bar+1]} `
103+ vs ` ${foo[((bar+1))]} ` or ` ${foo[$((bar+1))]} ` , ` ${foo[--i]} ` vs
104+ ` ${foo[((--i))]} ` .
102105
103- == Loop variable names
106+ ## Loop variable names
104107
105- Use i, j, k for loop-local indices; n and m for lengths; some other descriptive
106- name typically based on array name but in singular when looping over actual
107- values. If an index or value is to be accessed later on instead of being just
108- locally for looping, use a more descriptive and specific name for it.
108+ Use ` i ` , ` j ` , ` k ` for loop-local indices; ` n ` and ` m ` for lengths; some other
109+ descriptive name typically based on array name but in singular when looping
110+ over actual values. If an index or value is to be accessed later on instead of
111+ being just locally for looping, use a more descriptive and specific name for
112+ it.
109113
110- == Function names
114+ ## Function names
111115
112- Use the _comp_ prefix for all function names, and _comp_cmd_ for functions
116+ Use the ` _comp_ ` prefix for all function names, and ` _comp_cmd_ ` for functions
113117defined in per command completion files and not anywhere else. Prefixing with
114118an underscore helps keep the functions out of the way for most command name
115119completions (except obviously ones starting with an underscore or ones that have
@@ -120,14 +124,6 @@ It is known that a lot of functions in the tree do not follow this practice.
120124This is due to backwards compatibility reasons, but all functions introduced
121125after version 2.11 should follow this name prefix rule.
122126
123- /////////////////////////////////////////
127+ ## Variable naming
124128
125- == case/esac vs if
126-
127- == quoting
128-
129- == awk vs cut for simple cases
130-
131- == variable naming
132-
133- /////////////////////////////////////////
129+ To be written.
0 commit comments