aboutsummaryrefslogtreecommitdiffstats
path: root/CODINGSTYLE.md
diff options
context:
space:
mode:
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)
tree276c642818366b305681e238dec44fd25791dac9 /CODINGSTYLE.md
parentf76efb350abd5c0e37e3b93f2232ba6e814e17e6 (diff)
downloadaports-9551cb59d3439acb4d40e936fbff4f127f9da4b9.tar.gz
aports-9551cb59d3439acb4d40e936fbff4f127f9da4b9.tar.bz2
aports-9551cb59d3439acb4d40e936fbff4f127f9da4b9.tar.xz
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.md111
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 @@
+# Alpine Linux coding style
+
+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
+recommendations.
+
+## Language
+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
+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
+`abuild`.
+
+Double underscores are reserved and should not be used.
+```sh
+_my_variable="data"
+```
+
+### Bracing
+Curly braces for functions are on the same line.
+
+```sh
+prepare() {
+ ...
+}
+```
+
+Markers to indicate a compound statement, are on the same line.
+
+
+#### if ...; then
+```sh
+ if [ true ]; then
+ echo "It is so"
+ fi
+}
+```
+
+#### while ...; do
+```sh
+ while ...; do
+ ...
+ done
+```
+
+#### for ...; do
+```sh
+ for ...; do
+ ...
+ done
+```
+
+### Spacing
+All keywords and operators are separated by a space.
+
+For cleanliness sake, make sure there is however never any trailing whitespace.
+
+## Identation
+Indentation is one tab character, alignment is done using spaces. For example
+using the >------- characters to indicate a tab:
+```sh
+prepare()
+{
+>-------make DESTDIR="${pkgdir}" \
+>------- PREFIX="/usr"
+}
+```
+
+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
+Quote strings containing variables, command substitutions, spaces or shell meta
+characters, unless careful unquoted expansion is required.
+
+Don't quote _literal_ integers.
+
+### Bracing
+Only use curly braces around variables when needed.
+
+```sh
+foo="${foo}_bar"
+foo_bar="$foo"
+```
+
+## Subshell usage
+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.
+