From 9551cb59d3439acb4d40e936fbff4f127f9da4b9 Mon Sep 17 00:00:00 2001 From: Natanael Copa Date: Wed, 24 Jul 2019 16:00:35 +0000 Subject: 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 --- CODESTYLE.md | 90 ---------------------------------------------- CODINGSTYLE.md | 111 +++++++++++++++++++++++++++++++++++++++++++++++++++++++++ 2 files changed, 111 insertions(+), 90 deletions(-) delete mode 100644 CODESTYLE.md create mode 100644 CODINGSTYLE.md diff --git a/CODESTYLE.md b/CODESTYLE.md deleted file mode 100644 index e6a4e651141..00000000000 --- a/CODESTYLE.md +++ /dev/null @@ -1,90 +0,0 @@ -# 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 rules. - -## Language -Alpine Linux APKBUILD files are inherently just shell scripts. As such, they -should pass the shellcheck linter. - -## 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. -```sh -_my_variable="data" -``` - -### Bracing -Curly braces for functions are on the next line, to indicate a function. - -Markers to indicate a compound statement, are on the same line. - -```sh -prepare() -{ - if [ true ]; then - echo "It is so" - fi -} -``` - -### 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. - -## 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" -``` - -### 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. - -```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}" -``` - -## Subshell usage -Always 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. diff --git a/CODINGSTYLE.md b/CODINGSTYLE.md new file mode 100644 index 00000000000..3d44642e106 --- /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. + -- cgit v1.2.3