diff options
authorNatanael Copa <ncopa@alpinelinux.org>2019-07-24 16:00:35 +0000
committerNatanael Copa <ncopa@alpinelinux.org>2019-07-24 16:30:08 +0000
commit9551cb59d3439acb4d40e936fbff4f127f9da4b9 (patch)
parentf76efb350abd5c0e37e3b93f2232ba6e814e17e6 (diff)
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
-rw-r--r--CODINGSTYLE.md (renamed from CODESTYLE.md)79
1 files changed, 50 insertions, 29 deletions
diff --git a/CODESTYLE.md b/CODINGSTYLE.md
index e6a4e65114..3d44642e10 100644
--- a/CODESTYLE.md
@@ -2,35 +2,61 @@
Thank you for taking interest in contributing to our aports repository.
As consistency and readability are so important for the quality of our APKBUILD
-and thus the quality of Alpine Linux, we kindly ask to follow these rules.
+and thus the quality of Alpine Linux, we kindly ask to follow these
## Language
-Alpine Linux APKBUILD files are inherently just shell scripts. As such, they
-should pass the shellcheck linter.
+Alpine Linux APKBUILD files are inherently just POSIX shell scripts. Try avoid
+extensions, even if they work or are accepted by busybox ash. (using keyword
+`local` is an exception)
## Naming convention
-APKBUILD files uses snake_case. For example functions, variable names etc. are
-all lower-cased with using an underscore as a separator/space. Local 'private'
-variables and functions are pre-fixed with a single underscore. Double
-underscores are reserved and should not be used.
+Use snake_case. Functions, variables etc. should be lower-cased with
+underscores to separate words.
+Local 'private' variables and functions n global scope should be pre-fixed
+with a single underscore to avoid nameclash with internal variables in
+Double underscores are reserved and should not be used.
### Bracing
-Curly braces for functions are on the next line, to indicate a function.
+Curly braces for functions are on the same line.
+prepare() {
+ ...
Markers to indicate a compound statement, are on the same line.
+#### if ...; then
if [ true ]; then
echo "It is so"
+#### while ...; do
+ while ...; do
+ ...
+ done
+#### for ...; do
+ for ...; do
+ ...
+ done
### Spacing
All keywords and operators are separated by a space.
@@ -49,42 +75,37 @@ prepare()
This ensures code is always neatly aligned and properly indented.
+Space before tab should be avoided.
## Line length
A line should not be longer then 80 lines. While this is not a hard limit, it
is strongly recommended to avoid having longer lines, as long lines reduce
readability and invite deep nesting.
## Variables
### Quoting
-Always quote strings. As in shell there is no concept of data types (other then
-strings). There is no such thing as characters, integers or booleans. All data
-should thus be quoted.
+Quote strings containing variables, command substitutions, spaces or shell meta
+characters, unless careful unquoted expansion is required.
+Don't quote _literal_ integers.
### Bracing
-Always use curly braces around variables. While shells do not require this,
-being consistent in variable usage helps. Also there is no need to try to
-determine what the actual variable is and if it may not end up being empty.
+Only use curly braces around variables when needed.
-In the above, it could be argued it is immediately visible that ***$foo_bar***
-is the string 'foobar'. However if the variable is defined var away from the
-invocation, this is not clear any longer. To avoid these amigo ties, always
-use curly braces.
## Subshell usage
-Always use `$()` syntax, not backticks, as backticks are hard to spot.
+Use `$()` syntax, not backticks, as backticks are hard to spot.
## Sorting
Some items tend to benefit from being sorted. A list of sources, dependencies
etc. Always try to find a reasonable sort order, where alphabetically tends to
be the most useful one.
+## Eval
+`eval` is evil and should be avoided.