picnoir
/
Systemd
1
0
Fork 0
Code Issues Pull Requests Projects Releases Wiki Activity

CODING_STYLE: rename "Others" section to "Code Organization and Semantics" 

This is a bit of a grabbag, but it's the best I could come up with
without having lots of single-item sections.
This commit is contained in:
Lennart Poettering 2019-04-12 17:01:05 +02:00
parent 4467d39315
commit b4f12824a0
1 changed files with 33 additions and 37 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

70
docs/CODING_STYLE.md
View File

@ -55,53 +55,49 @@ title: Coding Style
- Do not write `foo ()`, write `foo()`. - Do not write `foo ()`, write `foo()`.
## Other ## Code Organization and Semantics
- Please name structures in `PascalCase` (with exceptions, such as public API - Please name structures in `PascalCase` (with exceptions, such as public API
structs), variables and functions in `snake_case`. structs), variables and functions in `snake_case`.
- Avoid static variables, except for caches and very few other - Avoid static variables, except for caches and very few other cases. Think
cases. Think about thread-safety! While most of our code is never about thread-safety! While most of our code is never used in threaded
used in threaded environments, at least the library code should make environments, at least the library code should make sure it works correctly
sure it works correctly in them. Instead of doing a lot of locking in them. Instead of doing a lot of locking for that, we tend to prefer using
for that, we tend to prefer using TLS to do per-thread caching (which TLS to do per-thread caching (which only works for small, fixed-size cache
only works for small, fixed-size cache objects), or we disable objects), or we disable caching for any thread that is not the main
caching for any thread that is not the main thread. Use thread. Use `is_main_thread()` to detect whether the calling thread is the
`is_main_thread()` to detect whether the calling thread is the main main thread.
thread.
- Do not write functions that clobber call-by-reference variables on - Do not write functions that clobber call-by-reference variables on
failure. Use temporary variables for these cases and change the failure. Use temporary variables for these cases and change the passed in
passed in variables only on success. variables only on success.
- The order in which header files are included doesn't matter too - The order in which header files are included doesn't matter too
much. systemd-internal headers must not rely on an include order, so much. systemd-internal headers must not rely on an include order, so it is
it is safe to include them in any order possible. safe to include them in any order possible. However, to not clutter global
However, to not clutter global includes, and to make sure internal includes, and to make sure internal definitions will not affect global
definitions will not affect global headers, please always include the headers, please always include the headers of external components first
headers of external components first (these are all headers enclosed (these are all headers enclosed in <>), followed by our own exported headers
in <>), followed by our own exported headers (usually everything (usually everything that's prefixed by `sd-`), and then followed by internal
that's prefixed by `sd-`), and then followed by internal headers. headers. Furthermore, in all three groups, order all includes alphabetically
Furthermore, in all three groups, order all includes alphabetically
so duplicate includes can easily be detected. so duplicate includes can easily be detected.
- Please avoid using global variables as much as you can. And if you - Please avoid using global variables as much as you can. And if you do use
do use them make sure they are static at least, instead of them make sure they are static at least, instead of exported. Especially in
exported. Especially in library-like code it is important to avoid library-like code it is important to avoid global variables. Why are global
global variables. Why are global variables bad? They usually hinder variables bad? They usually hinder generic reusability of code (since they
generic reusability of code (since they break in threaded programs, break in threaded programs, and usually would require locking there), and as
and usually would require locking there), and as the code using them the code using them has side-effects make programs non-transparent. That
has side-effects make programs non-transparent. That said, there are said, there are many cases where they explicitly make a lot of sense, and are
many cases where they explicitly make a lot of sense, and are OK to OK to use. For example, the log level and target in `log.c` is stored in a
use. For example, the log level and target in `log.c` is stored in a global variable, and that's OK and probably expected by most. Also in many
global variable, and that's OK and probably expected by most. Also cases we cache data in global variables. If you add more caches like this,
in many cases we cache data in global variables. If you add more please be careful however, and think about threading. Only use static
caches like this, please be careful however, and think about variables if you are sure that thread-safety doesn't matter in your
threading. Only use static variables if you are sure that case. Alternatively, consider using TLS, which is pretty easy to use with
thread-safety doesn't matter in your case. Alternatively, consider gcc's `thread_local` concept. It's also OK to store data that is inherently
using TLS, which is pretty easy to use with gcc's `thread_local` global in global variables, for example data parsed from command lines, see
concept. It's also OK to store data that is inherently global in
global variables, for example data parsed from command lines, see
below. below.
- You might wonder what kind of common code belongs in `src/shared/` and what - You might wonder what kind of common code belongs in `src/shared/` and what