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

1 files changed, 50 insertions, 29 deletions

diff --git a/CODESTYLE.md b/CODINGSTYLE.md
index e6a4e65114..3d44642e10 100644
--- a/CODESTYLE.md
+++ b/CODINGSTYLE.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
+recommendations.
 
 ## 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
+`abuild`.
+
+Double underscores are reserved and should not be used.
 ```sh
 _my_variable="data"
 ```
 
 ### Bracing
-Curly braces for functions are on the next line, to indicate a function.
+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
-prepare()
-{
 	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.
 
@@ -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.
-```sh
-pkgver="0"
-```
+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.
 
 ```sh
-foo_bar="foobar"
-foo="bar"
-```
-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.
-```sh
 foo="${foo}_bar"
-foo_bar="${foo}"
+foo_bar="$foo"
 ```
 
 ## 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.
+