CODINGSTYLE.md 2.42 KB
Newer Older
Olliver Schinagl's avatar
Olliver Schinagl committed
1 2 3 4
# 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
5 6
and thus the quality of Alpine Linux, we kindly ask to follow these
recommendations.
Olliver Schinagl's avatar
Olliver Schinagl committed
7 8

## Language
Simon F's avatar
Simon F committed
9
Alpine Linux APKBUILD files are inherently just POSIX shell scripts. Please avoid
10 11
extensions, even if they work or are accepted by busybox ash. (using keyword
`local` is an exception)
Olliver Schinagl's avatar
Olliver Schinagl committed
12 13

## Naming convention
14 15 16
Use snake_case. Functions, variables etc. should be lower-cased with
underscores to separate words.

Simon F's avatar
Simon F committed
17 18
Local 'private' variables and functions in global scope should be prefixed
with a single underscore to avoid name collisions with internal variables in
19 20 21
`abuild`.

Double underscores are reserved and should not be used.
Olliver Schinagl's avatar
Olliver Schinagl committed
22 23 24 25 26
```sh
_my_variable="data"
```

### Bracing
Simon F's avatar
Simon F committed
27
Curly braces for functions should be on the same line.
28 29 30 31 32 33

```sh
prepare() {
	...
}
```
Olliver Schinagl's avatar
Olliver Schinagl committed
34

Simon F's avatar
Simon F committed
35
Markers to indicate a compound statement should be on the same line.
Olliver Schinagl's avatar
Olliver Schinagl committed
36

37 38

#### if ...; then
Olliver Schinagl's avatar
Olliver Schinagl committed
39 40 41 42 43 44 45
```sh
	if [ true ]; then
		echo "It is so"
	fi
}
```

46 47 48 49 50 51 52 53 54
#### while ...; do
```sh
	while ...; do
		...
	done
```

#### for ...; do
```sh
Simon F's avatar
Simon F committed
55
	for x in foo bar baz; do
56 57 58 59
		...
	done
```

Olliver Schinagl's avatar
Olliver Schinagl committed
60 61 62
### Spacing
All keywords and operators are separated by a space.

Simon F's avatar
Simon F committed
63
For cleanliness sake, ensure there is no trailing whitespace.
Olliver Schinagl's avatar
Olliver Schinagl committed
64 65

## Identation
Simon F's avatar
Simon F committed
66 67
Indentation is one tab character per level, alignment is done using spaces.
For example (using the >------- characters to indicate a tab):
Olliver Schinagl's avatar
Olliver Schinagl committed
68
```sh
Simon F's avatar
Simon F committed
69
build()
Olliver Schinagl's avatar
Olliver Schinagl committed
70 71 72 73 74 75 76 77
{
>-------make DESTDIR="${pkgdir}" \
>-------     PREFIX="/usr"
}
```

This ensures code is always neatly aligned and properly indented.

78 79
Space before tab should be avoided.

Olliver Schinagl's avatar
Olliver Schinagl committed
80
## Line length
81
A line should not be longer than 80 characters. While this is not a hard limit, it
Olliver Schinagl's avatar
Olliver Schinagl committed
82 83 84 85
is strongly recommended to avoid having longer lines, as long lines reduce
readability and invite deep nesting.

## Variables
86

Olliver Schinagl's avatar
Olliver Schinagl committed
87
### Quoting
88 89 90 91
Quote strings containing variables, command substitutions, spaces or shell meta
characters, unless careful unquoted expansion is required.

Don't quote _literal_ integers.
Olliver Schinagl's avatar
Olliver Schinagl committed
92 93

### Bracing
94
Only use curly braces around variables when needed.
Olliver Schinagl's avatar
Olliver Schinagl committed
95 96 97

```sh
foo="${foo}_bar"
98
foo_bar="$foo"
Olliver Schinagl's avatar
Olliver Schinagl committed
99 100 101
```

## Subshell usage
Simon F's avatar
Simon F committed
102
Use `$()` syntax, not backticks.
Olliver Schinagl's avatar
Olliver Schinagl committed
103 104 105 106 107

## 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.
108 109 110 111

## Eval
`eval` is evil and should be avoided.