docs: Add note to keep header files as lean as possible to CODING_STYLE.md

diff --git a/docs/CODING_STYLE.md b/docs/CODING_STYLE.md
index 2b8cf694208cea80ef26db4b13d8480bdccd54be..efc9d2ae3e67c322ebc479c4c0a46e7cb42f6e85 100644 (file)
--- 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