aboutsummaryrefslogtreecommitdiffstats
path: root/Documentation/CodingStyle
diff options
context:
space:
mode:
authorJosh Triplett <josh@joshtriplett.org>2014-10-29 14:15:17 -0400
committerJonathan Corbet <corbet@lwn.net>2014-11-03 11:46:02 -0500
commit21228a1868692c34ade648dbb0bc3db0069ab551 (patch)
treea545010214c9e42931bef25b2fc06880be885bec /Documentation/CodingStyle
parent0df1f2487d2f0d04703f142813d53615d62a1da4 (diff)
CodingStyle: Add a chapter on conditional compilation
Document several common practices and conventions regarding conditional compilation, most notably the preference for ifdefs in headers rather than .c files. Signed-off-by: Josh Triplett <josh@joshtriplett.org> Acked-by: Geert Uytterhoeven <geert@linux-m68k.org> Signed-off-by: Jonathan Corbet <corbet@lwn.net>
Diffstat (limited to 'Documentation/CodingStyle')
-rw-r--r--Documentation/CodingStyle43
1 files changed, 43 insertions, 0 deletions
diff --git a/Documentation/CodingStyle b/Documentation/CodingStyle
index 3171822c22a5..9f28b140dc89 100644
--- a/Documentation/CodingStyle
+++ b/Documentation/CodingStyle
@@ -845,6 +845,49 @@ next instruction in the assembly output:
845 : /* outputs */ : /* inputs */ : /* clobbers */); 845 : /* outputs */ : /* inputs */ : /* clobbers */);
846 846
847 847
848 Chapter 20: Conditional Compilation
849
850Wherever possible, don't use preprocessor conditionals (#if, #ifdef) in .c
851files; doing so makes code harder to read and logic harder to follow. Instead,
852use such conditionals in a header file defining functions for use in those .c
853files, providing no-op stub versions in the #else case, and then call those
854functions unconditionally from .c files. The compiler will avoid generating
855any code for the stub calls, producing identical results, but the logic will
856remain easy to follow.
857
858Prefer to compile out entire functions, rather than portions of functions or
859portions of expressions. Rather than putting an ifdef in an expression, factor
860out part or all of the expression into a separate helper function and apply the
861conditional to that function.
862
863If you have a function or variable which may potentially go unused in a
864particular configuration, and the compiler would warn about its definition
865going unused, mark the definition as __maybe_unused rather than wrapping it in
866a preprocessor conditional. (However, if a function or variable *always* goes
867unused, delete it.)
868
869Within code, where possible, use the IS_ENABLED macro to convert a Kconfig
870symbol into a C boolean expression, and use it in a normal C conditional:
871
872 if (IS_ENABLED(CONFIG_SOMETHING)) {
873 ...
874 }
875
876The compiler will constant-fold the conditional away, and include or exclude
877the block of code just as with an #ifdef, so this will not add any runtime
878overhead. However, this approach still allows the C compiler to see the code
879inside the block, and check it for correctness (syntax, types, symbol
880references, etc). Thus, you still have to use an #ifdef if the code inside the
881block references symbols that will not exist if the condition is not met.
882
883At the end of any non-trivial #if or #ifdef block (more than a few lines),
884place a comment after the #endif on the same line, noting the conditional
885expression used. For instance:
886
887#ifdef CONFIG_SOMETHING
888...
889#endif /* CONFIG_SOMETHING */
890
848 891
849 Appendix I: References 892 Appendix I: References
850 893