Commit 9551cb59 authored by Natanael Copa's avatar Natanael Copa

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
parent f76efb35
......@@ -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.
Markdown is supported
0%
or
You are about to add 0 people to the discussion. Proceed with caution.
Finish editing this message first!
Please register or to comment