diff options
author | Natanael Copa <ncopa@alpinelinux.org> | 2019-07-24 16:00:35 +0000 |
---|---|---|
committer | Natanael Copa <ncopa@alpinelinux.org> | 2019-07-24 16:30:08 +0000 |
commit | 9551cb59d3439acb4d40e936fbff4f127f9da4b9 (patch) | |
tree | 276c642818366b305681e238dec44fd25791dac9 /CODINGSTYLE.md | |
parent | f76efb350abd5c0e37e3b93f2232ba6e814e17e6 (diff) | |
download | alpine_aports-9551cb59d3439acb4d40e936fbff4f127f9da4b9.tar.bz2 alpine_aports-9551cb59d3439acb4d40e936fbff4f127f9da4b9.tar.xz alpine_aports-9551cb59d3439acb4d40e936fbff4f127f9da4b9.zip |
CODINSTYLE: adjust to current defacto standards
- rename to CODINGSTYLE.md
- use "recommendations" instead of "rules"
- remove reference to unpackaged shellcheck
- try shorten text
- mention eval
Diffstat (limited to 'CODINGSTYLE.md')
-rw-r--r-- | CODINGSTYLE.md | 111 |
1 files changed, 111 insertions, 0 deletions
diff --git a/CODINGSTYLE.md b/CODINGSTYLE.md new file mode 100644 index 0000000000..3d44642e10 --- /dev/null +++ b/CODINGSTYLE.md | |||
@@ -0,0 +1,111 @@ | |||
1 | # Alpine Linux coding style | ||
2 | |||
3 | Thank you for taking interest in contributing to our aports repository. | ||
4 | As consistency and readability are so important for the quality of our APKBUILD | ||
5 | and thus the quality of Alpine Linux, we kindly ask to follow these | ||
6 | recommendations. | ||
7 | |||
8 | ## Language | ||
9 | Alpine Linux APKBUILD files are inherently just POSIX shell scripts. Try avoid | ||
10 | extensions, even if they work or are accepted by busybox ash. (using keyword | ||
11 | `local` is an exception) | ||
12 | |||
13 | ## Naming convention | ||
14 | Use snake_case. Functions, variables etc. should be lower-cased with | ||
15 | underscores to separate words. | ||
16 | |||
17 | Local 'private' variables and functions n global scope should be pre-fixed | ||
18 | with a single underscore to avoid nameclash with internal variables in | ||
19 | `abuild`. | ||
20 | |||
21 | Double underscores are reserved and should not be used. | ||
22 | ```sh | ||
23 | _my_variable="data" | ||
24 | ``` | ||
25 | |||
26 | ### Bracing | ||
27 | Curly braces for functions are on the same line. | ||
28 | |||
29 | ```sh | ||
30 | prepare() { | ||
31 | ... | ||
32 | } | ||
33 | ``` | ||
34 | |||
35 | Markers to indicate a compound statement, are on the same line. | ||
36 | |||
37 | |||
38 | #### if ...; then | ||
39 | ```sh | ||
40 | if [ true ]; then | ||
41 | echo "It is so" | ||
42 | fi | ||
43 | } | ||
44 | ``` | ||
45 | |||
46 | #### while ...; do | ||
47 | ```sh | ||
48 | while ...; do | ||
49 | ... | ||
50 | done | ||
51 | ``` | ||
52 | |||
53 | #### for ...; do | ||
54 | ```sh | ||
55 | for ...; do | ||
56 | ... | ||
57 | done | ||
58 | ``` | ||
59 | |||
60 | ### Spacing | ||
61 | All keywords and operators are separated by a space. | ||
62 | |||
63 | For cleanliness sake, make sure there is however never any trailing whitespace. | ||
64 | |||
65 | ## Identation | ||
66 | Indentation is one tab character, alignment is done using spaces. For example | ||
67 | using the >------- characters to indicate a tab: | ||
68 | ```sh | ||
69 | prepare() | ||
70 | { | ||
71 | >-------make DESTDIR="${pkgdir}" \ | ||
72 | >------- PREFIX="/usr" | ||
73 | } | ||
74 | ``` | ||
75 | |||
76 | This ensures code is always neatly aligned and properly indented. | ||
77 | |||
78 | Space before tab should be avoided. | ||
79 | |||
80 | ## Line length | ||
81 | A line should not be longer then 80 lines. While this is not a hard limit, it | ||
82 | is strongly recommended to avoid having longer lines, as long lines reduce | ||
83 | readability and invite deep nesting. | ||
84 | |||
85 | ## Variables | ||
86 | |||
87 | ### Quoting | ||
88 | Quote strings containing variables, command substitutions, spaces or shell meta | ||
89 | characters, unless careful unquoted expansion is required. | ||
90 | |||
91 | Don't quote _literal_ integers. | ||
92 | |||
93 | ### Bracing | ||
94 | Only use curly braces around variables when needed. | ||
95 | |||
96 | ```sh | ||
97 | foo="${foo}_bar" | ||
98 | foo_bar="$foo" | ||
99 | ``` | ||
100 | |||
101 | ## Subshell usage | ||
102 | Use `$()` syntax, not backticks, as backticks are hard to spot. | ||
103 | |||
104 | ## Sorting | ||
105 | Some items tend to benefit from being sorted. A list of sources, dependencies | ||
106 | etc. Always try to find a reasonable sort order, where alphabetically tends to | ||
107 | be the most useful one. | ||
108 | |||
109 | ## Eval | ||
110 | `eval` is evil and should be avoided. | ||
111 | |||