1# OpenThread Coding Conventions and Style 2 3- [1 C and C++](#c-and-c) 4 - [1.1 Standards](#standards) 5 - [1.2 Conventions and Best Practices](#conventions-and-best-practices) 6 - [1.3 Tightly-constrained Systems and Shared Infrastructure](#tightly-constrained-systems-and-shared-infrastructure) 7 - [1.4 Format and Style](#format-and-style) 8 - [1.5 Comments](#comments) 9- [2 Python](#python) 10 - [2.1 Standards](#standards) 11 - [2.2 Conventions and Best Practices](#conventions-and-best-practices) 12 - [2.3 Format and Style](#format-and-style) 13 14# C and C++ 15 16## Standards 17 18- C 19 - OpenThread uses and enforces the ISO9899:1999 (aka ISO C99, C99) C language standard as the minimum. 20- C++ 21 - OpenThread uses and enforces the ISO14882:2011 (aka ISO C++11, C++11) C++ language standard as the minimum. 22- Extensions 23 - Wherever possible, toolchain-specific (e.g GCC/GNU) extensions or the use of later standards shall be avoided or shall be leveraged through toolchain-compatibility preprocessor macros. 24 25## Conventions and Best Practices 26 27### Language Independent 28 29- Inline functions should be used judiciously. 30 - The use of code in headers and, more specifically, the use of the non-local scope inline functions should be avoided. Exception: Simple setters and getters are fine since the compiler can efficiently optimize these and make their overhead as low as a direct data member access. 31- Return Statements 32 - There should be one return statement per free function or method at the end of the free function or method. 33- Non-local Goto 34 - There should be no calls to the functions `setjmp` or `longjmp`. 35- Local Goto 36 - There should be no calls to the C/C++ keyword goto. Exception: The use of local gotos for the purposes of common error handling blocks and single points of function return at the bottom of a function. 37- C Preprocessor 38 - Use of the C preprocessor should be limited to file inclusion and simple macros. 39 - Macros shall not be defined within a function or a block and should be defined at the top of a file. 40 - All `#else`, `#elif`, and `#endif` preprocessor directives shall reside in the same file as the `#if` or `#ifdef` directive to which they are related. 41 - All `#endif` directives equal to or greater than 20 lines away from the `#if` or `#ifdef` directive to which they are related shall be decorated by language comment indicating the conditional they are associated with. 42 - Preprocessor `#include` directives in a file shall only be preceded by other preprocessor directives or comments. 43 - Preprocessor `#include` directives shall use brace (“<”) and (“>”) style for all public headers, including C and C++ standard library, or other first- and third-party public library headers. 44 - Preprocessor `#include` directives should use double quote (‘“‘) and (‘“‘) style for all private or relative headers. 45 - Preprocessor `#include` directives should be grouped, ordered, or sorted as follows: 46 - If the unit is a core/private header file, `"openthread-core-config.h"` should be the first header file included. 47 - If the unit is a core/private `.c` or `.cpp` file: 48 - If the unit has a corresponding header file, the unit's corresponding header file should be included before any other header file. 49 - If the unit has no corresponding header file, then it should directly include `"openthread-core-config.h"` before any other header file. 50 - C++ Standard Library headers 51 - C Standard Library headers 52 - Third-party library headers 53 - First-party library headers 54 - Private or local headers 55 - Alphanumeric order within each subgroup 56 - The preprocessor shall not be used to redefine reserved language keywords. 57 - Unused code shall not be disabled by commenting it out with C- or C++-style comments or with preprocessor `#if 0 ... #endif` semantics. 58 - Use of the preprocessor token concatenation operator '##' should be avoided. 59 - The `undef` preprocessor directive should be avoided and shall never be used to undefine a symbol from a foreign module. 60- Object Scope 61 - Data objects shall be declared at the smallest possible level of scope. 62 - No declaration in an inner scope shall hide or shadow a declaration in an outer scope. Compiler flags shall be set to flag and enforce this. 63- Unbounded Recursion 64 - There shall be no direct or indirect use of unbounded recursive function calls. 65- Symmetric APIs 66 - Wherever possible and appropriate, particularly around the management of resources, APIs should be symmetric. For example, if there is a free function or object method that allocates a resource, then there should be one that deallocates it. If there is a free function or object method that opens a file or network stream, then there should be one that closes it. 67- Use C stdint.h or C++ cstdint for Plain Old Data Types 68 - Standard, scalar data types defined in stdint.h (C) or cstdint (C++) should be used for basic signed and unsigned integer types, especially when size and serialization to non-volatile storage or across a network is concerned. Examples of these are: `uint8_t`, `int8_t`, etc. 69- Constant Qualifiers 70 - Read-only methods, global variables, stack variables, or data members are read-only should be qualified using the C or C++ `const` qualifier. 71 - Pointers or references to read-only objects or storage, including but not limited to function parameters, should be qualified using the C or C++ `const` qualifier. 72- Header Include Guard 73 - All C and C++ headers shall use preprocessor header include guards. 74 - The terminating endif preprocessor directive shall have a comment, C or C++ depending on the header type, containing the preprocessor symbol introduced by the ifndef directive starting the guard. 75 - The symbol used for the guard should be the file name, converted to all uppercase, with any spaces (“ “) or dots (“.”) converted to underscores (“\_”). 76- Function and Method Prototypes 77 - All void functions or methods shall explicitly declare and specify the void type keyword. 78- Unused parameters 79 - All unused parameters shall be declared as such using the `OT_UNUSED_VARIABLE` macro at the top of a function or method before all local variable declarations. 80 81### C 82 83- C / C++ Linkage Wrappers 84 - All header files intended to have C symbol linkage shall use “extern C” linkage wrappers. 85 86### C++ 87 88- Prefer Passing Parameters by Reference to Pointer 89 - Unlike C, C++ offers an alternate way to alias data over and above a pointer, the reference, indicated by the & symbol. Where appropriate, the reference should be preferred to the pointer. 90- Passing Base Scalars 91 - Size- and call frequency-based considerations should be made when passing scalars as to whether they should be passed by value or by constant reference; however, pass-by-value should generally be preferred. 92- Eliminate Unnecessary Destructors 93 - The creation of empty or useless destructors should be avoided. Empty or useless destructors should be removed. 94- Default Parameters 95 - When you declare C++ free functions and object methods, you should avoid or minimize using default parameters. 96 - When you declare C++ virtual object methods, you shall avoid using default parameters. 97- Global and Scoped Static Construction 98 - There shall be no use of global, static or otherwise, object construction. The use of scoped static object construction should be avoided. 99- C++-style Casts 100 - Wherever possible and practical, C++ style casts should be used and preferred to the C style cast equivalent. 101- Avoid `using namespace` Statements in Headers 102 - The C++ `using namespace` statement should not be used outside of object scope inside header files. 103 104## Tightly-constrained Systems and Shared Infrastructure 105 106- Heap-based resource allocation should be avoided. 107- There shall be no direct or indirect use of recursive function calls. 108- The use of virtual functions should be avoided. 109- The use of the C++ Standard Library shall be avoided. 110- The use of the C++ Standard Template Library (STL) should be avoided or minimized. 111- The use of the C++ templates should be avoided or minimized. 112- Code shall not use exceptions. 113- Code shall not use C++ runtime type information (RTTI), including facilities that rely upon it, such as `dynamic_cast` and `typeid`. 114 115## Format and Style 116 117- OpenThread uses `script/make-pretty` to reformat code and enforce code format and style. `script/make-pretty check` build target is included in OpenThread's continuous integration and must pass before a pull request is merged. 118 119- `script/make-pretty` requires [clang-format v9.0.0](https://releases.llvm.org/download.html#9.0.0) for C/C++ and [yapf v0.31.0](https://github.com/google/yapf) for Python. 120 121### File Names 122 123- File names should match the names and types of what is described in the file. If a file contains many declarations and definitions, the author should choose the one that predominantly describes or that makes the most sense. 124- File contents and names should be limited in the scope of what they contain. It may also be possible that there is too much stuff in one file and you need to break it up into multiple files. 125- File names should be all lower case. 126- File extensions shall be indicative and appropriate for the type and usage of the source or header file. 127 128### Naming 129 130- Names should be descriptive but not overly so and they should give some idea of scope and should be selected such that _wrong code looks wrong_. 131- Names shall not give any idea of type, such as is done with System Hungarian notation. 132- Case 133 - C preprocessor symbols should be all uppercase. 134 - All OpenThread class, namespace, structure, method, function, enumeration, and type names in the C/C++ language shall be in _upper camel case_. Exception: the top level OpenThread namespace 'ot'. 135 - All OpenThread instantiated names of instances of classes, namespaces, structures, methods, functions, enumerations, and types as well as method and function parameters in the C++ language shall be in _lower camel case_. 136- Symbol Qualification 137 - All OpenThread C public data types and free functions should have `ot` prepended to their name. 138 - All OpenThread C++ code should be in the ‘ot’ top-level namespace. 139- Scope 140 - All global data shall have a `g` prepended to the name to denote global scope. 141 - All static data shall have a `s` prepended to the name to denote static scope. 142 - All class or structure data members shall have a `m` prepended to the name to denote member scope. 143 - All free function or method parameters should have an `a` prepended to the name to denote function parameter scope. 144 - All variables that do not have such prefixes shall be assumed to be function local scope. 145 146### White Space 147 148- Indentation shall be 4 space characters. 149- Conditionals shall always appear on a separate line from the code to execute as a result of the condition. 150- Scoped Variable declarations 151 - All scoped (i.e. stack) variable declarations should be placed together at the top of the enclosing scope in which they are used. 152 - There shall be an empty line after all such variable declarations. 153 - The names of all variable declarations should be left aligned. 154- Data Member declarations 155 - All data member declarations should be placed together. 156 - The names of all data member declarations should be left aligned. 157 - The data member declarations for C++ classes should be placed at the end or tail of the class. 158- Braces 159 - Braces should go on their own lines. 160 - Statements should never be on the same line following a closing brace. 161- Keywords 162 - There should be a single space after language-reserved keywords (for, while, if, etc). 163 164## Comments 165 166- All code should use Doxygen to: 167 - Detail what the various source and header files are and how they fit into the broader context. 168 - Detail what the various C++ namespaces are. 169 - Detail what the constants, C preprocessor definitions, and enumerations are. 170 - Detail what the globals are and how they are to be used. 171 - Detail what the free function and object / class methods are and how they are to be used, what their parameters are, and what their return values are. 172 - Detail any other important technical information or theory of operation unique and relevant to the stack that is not otherwise captured in architecture, design, or protocol documentation. 173- Every public, and ideally private, free function and class method should likewise have a prologue comment that: 174 - Briefly describes what it is and what it does. 175 - Describes in detail, optionally, what it is and what it does. 176 - Describes the purpose, function, and influence of each parameter as well as whether it is an input, an output, or both. 177 - Describes the return value, if present, and the expected range or constraints of it. 178 179# Python 180 181## Standards 182 183- OpenThread uses and enforces Python 3. 184 185## Conventions and Best Practices 186 187- Run `pylint` over your code. `pylint` is a tool for finding bugs and style problems in Python source code. It finds problems that are typically caught by a compiler for less dynamic languages like C and C++. Because of the dynamic nature of Python, some warnings may be incorrect; however, spurious warnings should be fairly infrequent. 188 189## Format and Style 190 191- All code should adhere to [Google Python Style Guide](https://google.github.io/styleguide/pyguide.html) except maximum line length being 119. 192
