openbmc/docs/cpp-style-and-conventions.md

41 We also strive to keep the codebase up-to-date with the latest recommended
48 of this document enforced by tools as possible by, for example, clang-format and
49 clang-tidy.
51 For those coming to the project from pre-C++11 environments we strongly
57 OpenBMC targets embedded processors that typically have 32-64MB of flash and
58 similar processing power of a typical smart-watch available in 2016. This means
64 From a macro-optimization perspective, we expect all solutions to have an
89 - NL.10 Avoid CamelCase
90 - NL.17 Use K&R-derived layout
105 1. Use is done as a header-only library. This allows unused functions and
122 size over printf-style operations, due to individual function calls for each
123 appended value. We therefore do not use iostreams, or iostream-style APIs, for
127 clearer and similar-sized code. iostream may be used in those situations.
135 - Line length should be limited to 80 characters.
136 - Indentation should be done with 4 space characters.
137 - Files should use Unix-style newlines (\n).
139 ### Clang Formatting
142 [clang-format](https://clang.llvm.org/docs/ClangFormat.html) if desired. The
144 check-in if a .clang_format file is found within the root directory of the
146 check-in.
148 If a custom configuration is desired, such as using different clang formatting
149 for C and C++ files, a format-code.sh script can be created, which can for
150 example use different .clang\* files as input depending on the file type. The
151 format-code.sh script will be executed as part of CI if found in the root
153 modified after running it (same check as running clang).
155 OpenBMC requires a clang-format of version 6.0 or greater. An example of how to
156 run clang-format against all code in your repo can be found by referencing the
157 [tool](https://github.com/openbmc/openbmc-build-scripts/blob/master/scripts/format-code.sh)
160 [Example .clang-format](https://www.github.com/openbmc/docs/blob/master/style/cpp/.clang-format)
164 - Utilize 'Allman' style brackets. Brackets are on their own line at the same
181 - Even one line conditional and loop statements should have brackets.
197 - Content within a namespace should be at the same indentation level as the
209 - Content within a class / struct should be indented.
219 - Content within a function / conditional / loop should be indented.
234 - Switch / case statements should be indented.
253 - Labels should be indented so they appear at 1 level less than the current
280 - We generally abstain from any prefix or suffix on names.
281 - Acronyms should be same-case throughout and follow the requirements as in
288 /// Wrong: type and variable are mixed-case, function isn't lowerCamelCase.
298 c-libraries
299 cpp-libraries (including openbmc libraries)
307 c-libraries
308 cpp-libraries
315 - C++ headers should end in ".hpp". C headers should end in ".h".
316 - C++ files should be named with lower_snake_case.
320 - Prefer 'using' over 'typedef' for type aliases.
321 - Structs, classes, enums, and typed template parameters should all be in
323 - Prefer namespace scoping rather than long names with prefixes.
324 - A single-word type alias within a struct / class may be lowercase to match STL
325   conventions (`using type = T`) while a multi-word type alias should be
327 - Exception: A library API may use lower_snake_case to match conventions of the
330 - Exception: A for-convenience template type alias of a template class may end
345 - Variables should all be lowerCamelCase, including class members, with no
350 - Functions should all be lowerCamelCase.
351 - Exception: A library API may use lower_snake-case to match conventions of the
357 - Constants and enum members should be named like variables in lowerCamelCase.
361 - Namespaces should be lower_snake_case.
362 - Top-level namespace should be named based on the containing repository.
363 - Favor a namespace called 'details' or 'internal' to indicate the equivalent of
368 Prefer '#pragma once' header guard over '#ifndef'-style.
372 - Follow NL.18: Use C++-style declarator layout.
379 - Follow NL.15: Use spaces sparingly.
381 - Insert whitespace after a conditional and before parens.
389 - Insert whitespace around binary operators for readability.
392 foo((a-1)/b,c-2); /// Incorrect.
393 foo((a - 1) / b, c - 2); /// Correct.
396 - Do not insert whitespace around unary operators.
401 a = b -> c;  /// Incorrect.
405 - Do not insert whitespace inside parens or between a function call and
417 - Prefer line-breaks after operators to show continuation.
427 - Long lines should have continuation start at the same level as the parens or
428   all all items inside the parens should be at a 2-level indent.
450 - Always use `size_t` or `ssize_t` for things that are sizes, counts, etc. You
454 - Use `uint8_t`, `int16_t`, `uint32_t`, `int64_t`, etc. for types where size is