From 352fee103bd78b957cd286f35d8ba92d8b63f82e Mon Sep 17 00:00:00 2001 From: Daan De Meyer Date: Sat, 19 Apr 2025 10:22:37 +0200 Subject: [PATCH] docs: Add note to keep header files as lean as possible to CODING_STYLE.md --- docs/CODING_STYLE.md | 42 ++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 42 insertions(+) diff --git a/docs/CODING_STYLE.md b/docs/CODING_STYLE.md index 2b8cf694208..efc9d2ae3e6 100644 --- a/docs/CODING_STYLE.md +++ b/docs/CODING_STYLE.md @@ -302,6 +302,48 @@ SPDX-License-Identifier: LGPL-2.1-or-later #include "manager.h" ``` +- Please keep header files as lean as possible. Prefer implementing functions in + the implementation (.c) file over implementing them in the corresponding + header file. Inline functions in the header are allowed if they are just a few + lines and don't require including any extra header files that would otherwise + not have to be included. Similarly, prefer forward declarations of structs + over including the corresponding header file. Keeping header files as lean as + possible speeds up incremental builds when header files are changed (either by + yourself when working on a pull request or as part of rebasing onto the main + branch) as each file that (transitively) includes a header that was changed + needs to be recompiled. By keeping the number of header files included by + other header files low, we reduce the impact of modifying header files on + incremental builds as much as possible. + + Bad: + + ```c + // source.h + + #include "log.h" + + static inline void my_function_that_logs(void) { + log_error("oops"); + } + ``` + + Good: + + ```c + // source.h + + void my_function_that_logs(void); + + // source.c + + #include "header.h" + #include "log.h" + + void my_function_that_logs(void) { + log_error("oops"); + } + ``` + - The order in which header files are included doesn't matter too much. systemd-internal headers must not rely on an include order, so it is safe to include them in any order possible. However, to not clutter global -- 2.47.3