summaryrefslogtreecommitdiff
diff options
context:
space:
mode:
authorLennart Poettering <lennart@poettering.net>2019-04-12 16:58:46 +0200
committerLennart Poettering <lennart@poettering.net>2019-04-12 16:59:48 +0200
commit4467d39315f1ca2470dde117e7828b261e1ad948 (patch)
tree8ae730e2312825db6ca80208e17616e1aa86ea92
parent78e5b4d7eeb00546d512a3bf04f42b9885ae9e07 (diff)
downloadsystemd-4467d39315f1ca2470dde117e7828b261e1ad948.tar.gz
CODING_STYLE: split out section about runtime behaviour
-rw-r--r--docs/CODING_STYLE.md64
1 files changed, 33 insertions, 31 deletions
diff --git a/docs/CODING_STYLE.md b/docs/CODING_STYLE.md
index cb256c8447..9b2fd5cc84 100644
--- a/docs/CODING_STYLE.md
+++ b/docs/CODING_STYLE.md
@@ -60,10 +60,6 @@ title: Coding Style
- Please name structures in `PascalCase` (with exceptions, such as public API
structs), variables and functions in `snake_case`.
-- Be exceptionally careful when formatting and parsing floating point
- numbers. Their syntax is locale dependent (i.e. `5.000` in en_US is
- generally understood as 5, while in de_DE as 5000.).
-
- Avoid static variables, except for caches and very few other
cases. Think about thread-safety! While most of our code is never
used in threaded environments, at least the library code should make
@@ -89,16 +85,6 @@ title: Coding Style
Furthermore, in all three groups, order all includes alphabetically
so duplicate includes can easily be detected.
-- Avoid leaving long-running child processes around, i.e. `fork()`s that
- are not followed quickly by an `execv()` in the child. Resource
- management is unclear in this case, and memory CoW will result in
- unexpected penalties in the parent much, much later on.
-
-- Don't block execution for arbitrary amounts of time using `usleep()`
- or a similar call, unless you really know what you do. Just "giving
- something some time", or so is a lazy excuse. Always wait for the
- proper event, instead of doing time-based poll loops.
-
- Please avoid using global variables as much as you can. And if you
do use them make sure they are static at least, instead of
exported. Especially in library-like code it is important to avoid
@@ -118,13 +104,6 @@ title: Coding Style
global variables, for example data parsed from command lines, see
below.
-- Make sure to enforce limits on every user controllable resource. If the user
- can allocate resources in your code, your code must enforce some form of
- limits after which it will refuse operation. It's fine if it is hard-coded (at
- least initially), but it needs to be there. This is particularly important
- for objects that unprivileged users may allocate, but also matters for
- everything else any user may allocated.
-
- You might wonder what kind of common code belongs in `src/shared/` and what
belongs in `src/basic/`. The split is like this: anything that is used to
implement the public shared object we provide (sd-bus, sd-login, sd-id128,
@@ -156,16 +135,6 @@ title: Coding Style
aren't, we are happy to use GNU or Linux APIs, and expect non-GNU
implementations of libc to catch up with glibc.
-- Whenever installing a signal handler, make sure to set `SA_RESTART` for it, so
- that interrupted system calls are automatically restarted, and we minimize
- hassles with handling `EINTR` (in particular as `EINTR` handling is pretty broken
- on Linux).
-
-- When applying C-style unescaping as well as specifier expansion on the same
- string, always apply the C-style unescaping fist, followed by the specifier
- expansion. When doing the reverse, make sure to escape `%` in specifier-style
- first (i.e. `%` → `%%`), and then do C-style escaping where necessary.
-
## Using C Constructs
- Preferably allocate local variables on the top of the block:
@@ -374,6 +343,39 @@ title: Coding Style
matters particularly in inner loops (but note that `strjoina()` cannot be
used there).
+## Runtime Behaviour
+
+- Avoid leaving long-running child processes around, i.e. `fork()`s that are
+ not followed quickly by an `execv()` in the child. Resource management is
+ unclear in this case, and memory CoW will result in unexpected penalties in
+ the parent much, much later on.
+
+- Don't block execution for arbitrary amounts of time using `usleep()` or a
+ similar call, unless you really know what you do. Just "giving something some
+ time", or so is a lazy excuse. Always wait for the proper event, instead of
+ doing time-based poll loops.
+
+- Whenever installing a signal handler, make sure to set `SA_RESTART` for it,
+ so that interrupted system calls are automatically restarted, and we minimize
+ hassles with handling `EINTR` (in particular as `EINTR` handling is pretty
+ broken on Linux).
+
+- When applying C-style unescaping as well as specifier expansion on the same
+ string, always apply the C-style unescaping fist, followed by the specifier
+ expansion. When doing the reverse, make sure to escape `%` in specifier-style
+ first (i.e. `%` → `%%`), and then do C-style escaping where necessary.
+
+- Be exceptionally careful when formatting and parsing floating point
+ numbers. Their syntax is locale dependent (i.e. `5.000` in en_US is generally
+ understood as 5, while in de_DE as 5000.).
+
+- Make sure to enforce limits on every user controllable resource. If the user
+ can allocate resources in your code, your code must enforce some form of
+ limits after which it will refuse operation. It's fine if it is hard-coded
+ (at least initially), but it needs to be there. This is particularly
+ important for objects that unprivileged users may allocate, but also matters
+ for everything else any user may allocated.
+
## Types
- Think about the types you use. If a value cannot sensibly be negative, do not