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 - This compilation unit's corresponding header, if any. 47 - C++ Standard Library headers 48 - C Standard Library headers 49 - Third-party library headers 50 - First-party library headers 51 - Private or local headers 52 - Alphanumeric order within each subgroup 53 - The preprocessor shall not be used to redefine reserved language keywords. 54 - Unused code shall not be disabled by commenting it out with C- or C++-style comments or with preprocessor `#if 0 ... #endif` semantics. 55 - Use of the preprocessor token concatenation operator '##' should be avoided. 56 - The `undef` preprocessor directive should be avoided and shall never be used to undefine a symbol from a foreign module. 57- Object Scope 58 - Data objects shall be declared at the smallest possible level of scope. 59 - 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. 60- Unbounded Recursion 61 - There shall be no direct or indirect use of unbounded recursive function calls. 62- Symmetric APIs 63 - 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. 64- Use C stdint.h or C++ cstdint for Plain Old Data Types 65 - 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. 66- Constant Qualifiers 67 - Read-only methods, global variables, stack variables, or data members are read-only should be qualified using the C or C++ `const` qualifier. 68 - 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. 69- Header Include Guard 70 - All C and C++ headers shall use preprocessor header include guards. 71 - 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. 72 - The symbol used for the guard should be the file name, converted to all uppercase, with any spaces (“ “) or dots (“.”) converted to underscores (“\_”). 73- Function and Method Prototypes 74 - All void functions or methods shall explicitly declare and specify the void type keyword. 75 76### C 77 78- C / C++ Linkage Wrappers 79 - All header files intended to have C symbol linkage shall use “extern C” linkage wrappers. 80 81### C++ 82 83- Prefer Passing Parameters by Reference to Pointer 84 - 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. 85- Passing Base Scalars 86 - 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. 87- Eliminate Unnecessary Destructors 88 - The creation of empty or useless destructors should be avoided. Empty or useless destructors should be removed. 89- Default Parameters 90 - When you declare C++ free functions and object methods, you should avoid or minimize using default parameters. 91 - When you declare C++ virtual object methods, you shall avoid using default parameters. 92- Global and Scoped Static Construction 93 - There shall be no use of global, static or otherwise, object construction. The use of scoped static object construction should be avoided. 94- C++-style Casts 95 - Wherever possible and practical, C++ style casts should be used and preferred to the C style cast equivalent. 96- Avoid `using namespace` Statements in Headers 97 - The C++ `using namespace` statement should not be used outside of object scope inside header files. 98 99## Tightly-constrained Systems and Shared Infrastructure 100 101- Heap-based resource allocation should be avoided. 102- There shall be no direct or indirect use of recursive function calls. 103- The use of virtual functions should be avoided. 104- The use of the C++ Standard Library shall be avoided. 105- The use of the C++ Standard Template Library (STL) should be avoided or minimized. 106- The use of the C++ templates should be avoided or minimized. 107- Code shall not use exceptions. 108- Code shall not use C++ runtime type information (RTTI), including facilities that rely upon it, such as `dynamic_cast` and `typeid`. 109 110## Format and Style 111 112- OpenThread uses `script/make-pretty` to reformat code and enforce code format and style. `script/make-pretty check` is included in OpenThread's continuous integration and must pass before a pull request is merged. 113 114- `script/make-pretty` requires [clang-format v14.0.0](https://releases.llvm.org/download.html#14.0.0) for C/C++ and [yapf](https://github.com/google/yapf) for Python. 115 116### File Names 117 118- 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. 119- 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. 120- File names should be all lower case. 121- File extensions shall be indicative and appropriate for the type and usage of the source or header file. 122 123### Naming 124 125- 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_. 126- Names shall not give any idea of type, such as is done with System Hungarian notation. 127- Case 128 - C preprocessor symbols should be all uppercase. 129 - 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'. 130 - 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_. 131- Symbol Qualification 132 - All OpenThread C public data types and free functions should have `ot` prepended to their name. 133 - All OpenThread C++ code should be in the ‘ot’ top-level namespace. 134- Scope 135 - All global data shall have a `g` prepended to the name to denote global scope. 136 - All static data shall have a `s` prepended to the name to denote static scope. 137 - All class or structure data members shall have a `m` prepended to the name to denote member scope. 138 - All free function or method parameters should have an `a` prepended to the name to denote function parameter scope. 139 - All variables that do not have such prefixes shall be assumed to be function local scope. 140 141### White Space 142 143- Indentation shall be 4 space characters. 144- Conditionals shall always appear on a separate line from the code to execute as a result of the condition. 145- Scoped Variable declarations 146 - All scoped (i.e. stack) variable declarations should be placed together at the top of the enclosing scope in which they are used. 147 - There shall be an empty line after all such variable declarations. 148 - The names of all variable declarations should be left aligned. 149- Data Member declarations 150 - All data member declarations should be placed together. 151 - The names of all data member declarations should be left aligned. 152 - The data member declarations for C++ classes should be placed at the end or tail of the class. 153- Braces 154 - Braces should go on their own lines. 155 - Statements should never be on the same line following a closing brace. 156- Keywords 157 - There should be a single space after language-reserved keywords (for, while, if, etc). 158 159## Comments 160 161- All code should use Doxygen to: 162 - Detail what the various source and header files are and how they fit into the broader context. 163 - Detail what the various C++ namespaces are. 164 - Detail what the constants, C preprocessor definitions, and enumerations are. 165 - Detail what the globals are and how they are to be used. 166 - 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. 167 - 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. 168- Every public, and ideally private, free function and class method should likewise have a prologue comment that: 169 - Briefly describes what it is and what it does. 170 - Describes in detail, optionally, what it is and what it does. 171 - Describes the purpose, function, and influence of each parameter as well as whether it is an input, an output, or both. 172 - Describes the return value, if present, and the expected range or constraints of it. 173 174# Python 175 176## Standards 177 178- OpenThread uses and enforces both Python 2 and Python 3. Support for Python 2 is a result of the fact that some current Linux distributions and Macs are still using 2.x as default. 179 180## Conventions and Best Practices 181 182- 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. 183 184## Format and Style 185 186- All code should adhere to [PEP 8](https://www.python.org/dev/peps/pep-0008/). 187