From ffeb46fc427ed98e5c76de612d4745ba77b43f8b Mon Sep 17 00:00:00 2001 From: Marian Buschsieweke Date: Sun, 14 Apr 2024 15:44:24 +0200 Subject: [PATCH] CODING_CONVENTIONS.md: Add IWYU policy This makes an implicit agreement that code should include the headers is uses, no more and no less, explicit. It also recommends using tooling (such as clangd) and adding IWUY pragma comments to aid those tools in common cases they otherwise would provide false positives. Co-authored-by: chrysn --- CODING_CONVENTIONS.md | 18 ++++++++++++++++++ 1 file changed, 18 insertions(+) diff --git a/CODING_CONVENTIONS.md b/CODING_CONVENTIONS.md index 3f52996d85bf..82cb971617c9 100644 --- a/CODING_CONVENTIONS.md +++ b/CODING_CONVENTIONS.md @@ -175,6 +175,24 @@ #endif ``` +### Include What You Use (IWYU) + +`#include` directives that are not actually needed should be removed to reduce +clutter and improve compilation speed. Similar: Try to add the corresponding +`#include`s for all the functions, macros, types, etc. used and do not rely on +`bar.h` to implicitly include `foo.h`, unless this is documented behavior. + +Tools such as [clang's Include Cleaner][clangd-include-cleaner] can help with +that. These tools may show false positives in cases where headers are *expected* +to be included indirectly: E.g. if `foo.h` is the public header that contains +common helpers and implementations, but a per platform `foo_arch.h` is included +from within `foo.h` for platform specific implementations. If in this scenario +only functions provided by `foo_arch.h` are included, the `#include` of `foo.h` +is considered as unused. To avoid this, one should add +[`/* IWYU pragma: export */`](https://github.com/include-what-you-use/include-what-you-use/blob/master/docs/IWYUPragmas.md) after `#include "foo_arch.h"` in `foo.h`. + +[clangd-include-cleaner]: https://clangd.llvm.org/design/include-cleaner + ## Header Guards All files are required to have header guards of the form