HALF ECHO LEARN / REFERENCE COLLECTION
v262.2docs/CODING_STYLE.md
Git blob: aa751e822831fad800e2bf6665dd7b82a6f61278
Lines 1001–1112 of 1,112
- Commit message subject lines should be prefixed with an appropriate component
name of some kind. For example, "journal: ", "nspawn: " and so on.
- Do not use "Signed-Off-By:" in your commit messages. That's a kernel thing we
don't do in the systemd project.
## Commenting
- The best place for code comments and explanations is in the code itself. Only
the second best is in git commit messages. The worst place is in the GitHub
PR cover letter. Hence, whenever you type a commit message consider for a
moment if what you are typing there wouldn't be a better fit for an in-code
comment. And if you type the cover letter of a PR, think hard if this
wouldn't be better as a commit message or even code comment. Comments are
supposed to be useful for somebody who reviews the code, and hence hiding
comments in git commits or PR cover letters makes reviews unnecessarily
hard. Moreover, while we rely heavily on GitHub's project management
infrastructure we'd like to keep everything that can reasonably be kept in
the git repository itself in the git repository, so that we can theoretically
move things elsewhere with the least effort possible.
- It's OK to reference GitHub PRs, GitHub issues and git commits from code
comments. Cross-referencing code, issues, and documentation is a good thing.
- Reasonable use of non-ASCII Unicode UTF-8 characters in code comments is
welcome. If your code comment contains an emoji or two this will certainly
brighten the day of the occasional reviewer of your code. Really! 😊
## Threading
- We generally avoid using threads, to the level this is possible. In
particular in the service manager/PID 1 threads are not OK to use. This is
because you cannot mix memory allocation in threads with use of glibc's
`clone()` call, or manual `clone()`/`clone3()` system call wrappers. Only
glibc's own `fork()` call will properly synchronize the memory allocation
locks around the process clone operation. This means that if a process is
cloned via `clone()`/`clone3()` and another thread currently has the
`malloc()` lock taken, it will be cloned in locked state to the child, and
thus can never be acquired in the child, leading to deadlocks. Hence, when
using `clone()`/`clone3()` there are only two ways out: never use threads in the
parent, or never do memory allocation in the child. For our uses we need
`clone()`/`clone3()` and hence decided to avoid threads. Of course, sometimes the
concurrency threads allow is beneficial, however we suggest forking off
worker *processes* rather than worker *threads* for this purpose, ideally
even with an `execve()` to remove the CoW trap situation `fork()` easily
triggers.
- A corollary of the above is: never use `clone()` where a `fork()` would do
too. Also consider using `posix_spawn()` which combines `clone()` +
`execve()` into one and has nice properties since it avoids becoming a CoW
trap by using `CLONE_VFORK` and `CLONE_VM` together.
- While we avoid forking off threads on our own, writing thread-safe code is a
good idea where it might end up running inside of libsystemd.so or
similar. Hence, use TLS (i.e. `thread_local`) where appropriate, and maybe
the occasional `pthread_once()`.
## Tests
- Use the assertion macros from `tests.h` (`ASSERT_GE()`, `ASSERT_OK()`, ...) to
make sure a descriptive error is logged when an assertion fails. If no assertion
macro exists for your specific use case, please add a new assertion macro in a
separate commit.
- Use `ASSERT_OK_ERRNO()` and similar macros instead of `ASSERT_OK()` when
calling glibc APIs that return the error in `errno`.
- When modifying existing tests, please convert the test to use the new assertion
macros from `tests.h` if it is not already using those.
## Integration Tests
- Never use `grep -q` in a pipeline, use `grep >/dev/null` instead. The former
will generate `SIGPIPE` for the previous command in the pipeline when it finds
a match which will cause the test to fail unexpectedly.
## Kernel Version Dependencies
- For entirely new functionality it's fine to rely on features of very recent
(released!) kernel versions. If a feature is added to the upstream kernel,
and a stable release is made, then it's immediately OK to merge *new*
functionality into systemd relying on it, as long as that functionality is
optional. (In some cases, it might be OK to merge a feature into systemd
slightly before the final kernel release that it is based on, as long as the
kernel development cycle has already progressed far enough that the feature
is unlikely to be still reverted – for example once RC2 of the kernel release
has been released.)
- For components that already have been released in a stable version
compatibility with older kernels must be retained, down to the "minimum
baseline" version as listed in the README, or the version current when the
component was added to our tree, whichever is newer.
- When adding a fallback path, please avoid checking for kernel versions, as
downstream distributions tend to backport features, and version checks are
not great replacements for feature checks hence.
- When adding a compatibility code path for an older kernel version, please add
a comment in the following style to the relevant codepath:
```c
// FIXME: This compatibility code path shall be removed once kernel X.Y
// becomes the new minimal baseline
```
When this syntax is followed we'll have an easier time tracking down these
codepaths and removing them when bumping baselines.
- Whenever support for a new kernel API feature is added, please update the
kernel feature/version list in README as well (as part of the same PR).