Inside Bitcoin

1# Developer Notes
2
3## Coding Style (General)
4
5Various coding styles have been used during the history of the codebase,
6and the result is not very consistent. However, we're now trying to converge to
7a single style, which is specified below. When writing patches, favor the new
8style over attempting to mimic the surrounding style, except for move-only
9commits.
10
11Do not submit patches solely to modify the style of existing code.
12
13## Coding Style (C++)
14
15- **Indentation and whitespace rules** as specified in
16[src/.clang-format](/src/.clang-format). You can use the provided
17[clang-format-diff script](/contrib/devtools/README.md#clang-format-diffpy)
18tool to clean up patches automatically before submission.
19  - Braces on new lines for classes, functions, methods.
20  - Braces on the same line for everything else (including structs).
21  - 4 space indentation (no tabs) for every block except namespaces.
22  - No indentation for `public`/`protected`/`private` or for `namespace`.
23  - No extra spaces inside parentheses; don't do `( this )`.
24  - No space after function names; one space after `if`, `for` and `while`.
25  - If an `if` only has a single-statement `then`-clause, it can appear
26    on the same line as the `if`, without braces. In every other case,
27    braces are required, and the `then` and `else` clauses must appear
28    correctly indented on a new line.
29  - There's no hard limit on line width, but prefer to keep lines to <100
30    characters if doing so does not decrease readability. Break up long
31    function declarations over multiple lines using the Clang Format
32    [AlignAfterOpenBracket](https://clang.llvm.org/docs/ClangFormatStyleOptions.html)
33    style option.
34
35- **Symbol naming conventions**. These are preferred in new code, but are not
36required when doing so would need changes to significant pieces of existing
37code.
38  - Variable (including function arguments) and namespace names are all lowercase and may use `_` to
39    separate words (snake_case).
40    - Class member variables have a `m_` prefix.
41    - Global variables have a `g_` prefix.
42  - Constant names are all uppercase, and use `_` to separate words.
43  - Enumerator constants may be `snake_case`, or `PascalCase`. They should not
44    be `ALL_CAPS`, according to the [C++ Core
45    Guidelines](https://isocpp.github.io/CppCoreGuidelines/CppCoreGuidelines#renum-caps),
46    to avoid clashing with macros.
47  - Class names, function names, and method names are UpperCamelCase
48    (PascalCase). Do not prefix class names with `C`. See [Internal interface
49    naming style](#internal-interface-naming-style) for an exception to this
50    convention.
51
52  - Test suite naming convention: The Boost test suite in file
53    `src/test/foo_tests.cpp` should be named `foo_tests`. Test suite names
54    must be unique.
55
56- **Miscellaneous**
57  - `++i` is preferred over `i++`.
58  - `static_assert` is preferred over `assert` where possible. Generally; compile-time checking is preferred over run-time checking.
59  - Use a named cast or functional cast, not a C-Style cast. When casting
60    between integer types, use functional casts such as `int(x)` or `int{x}`
61    instead of `(int) x`. When casting between more complex types, use `static_cast`.
62    Use `reinterpret_cast` and `const_cast` as appropriate.
63  - Prefer [`list initialization ({})`](https://isocpp.github.io/CppCoreGuidelines/CppCoreGuidelines#res-list) where possible.
64    For example `int x{0};` instead of `int x = 0;` or `int x(0);`
65
66For function calls a namespace should be specified explicitly, unless such functions have been declared within it.
67Otherwise, [argument-dependent lookup](https://en.cppreference.com/w/cpp/language/adl), also known as ADL, could be
68triggered that makes code harder to maintain and reason about:
69```c++
70#include <filesystem>
71
72namespace fs {
73class path : public std::filesystem::path
74{
75};
76// The intention is to disallow this function.
77bool exists(const fs::path& p) = delete;
78} // namespace fs
79
80int main()
81{
82    //fs::path p; // error
83    std::filesystem::path p; // compiled
84    exists(p); // ADL being used for unqualified name lookup
85}
86```
87
88Block style example:
89```c++
90int g_count{0};
91
92namespace foo {
93class Class
94{
95    std::string m_name;
96
97public:
98    bool Function(const std::string& s, int n)
99    {
100        // Comment summarising what this section of code does
101        for (int i = 0; i < n; ++i) {
102            int total_sum{0};
103            // When something fails, return early
104            if (!Something()) return false;
105            ...
106            if (SomethingElse(i)) {
107                total_sum += ComputeSomething(g_count);
108            } else {
109                DoSomething(m_name, total_sum);
110            }
111        }
112
113        // Success return is usually at the end
114        return true;
115    }
116}
117} // namespace foo
118```
119
120### Coding Style (C++ functions and methods)
121
122- When ordering function parameters, place input parameters first, then any
123  in-out parameters, followed by any output parameters.
124
125- *Rationale*: API consistency.
126
127- Prefer returning values directly to using in-out or output parameters. Use
128  `std::optional` where helpful for returning values.
129
130- *Rationale*: Less error-prone (no need for assumptions about what the output
131  is initialized to on failure), easier to read, and often the same or better
132  performance.
133
134- Generally, use `std::optional` to represent optional by-value inputs (and
135  instead of a magic default value, if there is no real default). Non-optional
136  input parameters should usually be values or const references, while
137  non-optional in-out and output parameters should usually be references, as
138  they cannot be null.
139
140### Coding Style (clang-tidy rules)
141
142The clang-tidy tool is used to check some rules. Please refer to the [upstream
143documentation](https://clang.llvm.org/extra/clang-tidy/checks/list.html) about
144the details and rationale for each rule.
145
146#### C++ Recursive Functions
147
148Recursion is checked by clang-tidy and thus must be made explicit. Use
149`NOLINTNEXTLINE(misc-no-recursion)` to suppress the check.
150
151#### C++ named arguments
152
153When passing named arguments, use a format that clang-tidy understands. The
154argument names can otherwise not be verified by clang-tidy.
155
156For example:
157
158```c++
159void function(Addrman& addrman, bool clear);
160
161int main()
162{
163    function(g_addrman, /*clear=*/false);
164}
165```
166
167#### Running clang-tidy
168
169To run clang-tidy on Ubuntu/Debian, install the dependencies:
170
171```sh
172apt install clang-tidy clang
173```
174
175Configure with clang as the compiler with the below command that should create a `compile_commands.json` file within the build directory:
176
177```sh
178cmake -B build -DCMAKE_C_COMPILER=clang -DCMAKE_CXX_COMPILER=clang++ -DCMAKE_EXPORT_COMPILE_COMMANDS=ON
179```
180
181The output is denoised of errors from external dependencies.
182
183To run clang-tidy on all source files using the checks mentioned in the `./src/.clang-tidy` file:
184
185```sh
186( cd ./src/ && run-clang-tidy -p ../build -j $(nproc) )
187```
188
189To run clang-tidy on one file:
190```sh
191( cd ./src/ && run-clang-tidy -p ../build -j $(nproc) ./path/to/single_file.cpp )
192```
193
194Optionally, append the `run-clang-tidy` command with the `-quiet` option to suppress printing of statistics and ignored warnings that can clutter the output. The `-fix` option also comes in handy to apply the fixes suggested by the tool but need to ensure that unrelated changes in the file are not committed.
195
196To run clang-tidy on the changed source lines:
197
198```sh
199git diff | ( cd ./src/ && clang-tidy-diff -p2 -path ../build -j $(nproc) )
200```
201
202## Coding Style (Doxygen-compatible comments)
203
204Bitcoin Core uses [Doxygen](https://www.doxygen.nl/) to generate its official documentation.
205
206Use Doxygen-compatible comment blocks for functions, methods, and fields.
207
208For example, to describe a function use:
209
210```c++
211/**
212 * ... Description ...
213 *
214 * @param[in]  arg1 input description...
215 * @param[in]  arg2 input description...
216 * @param[out] arg3 output description...
217 * @return Return cases...
218 * @throws Error type and cases...
219 * @pre  Pre-condition for function...
220 * @post Post-condition for function...
221 */
222bool function(int arg1, const char *arg2, std::string& arg3)
223```
224
225A complete list of `@xxx` commands can be found at https://www.doxygen.nl/manual/commands.html.
226As Doxygen recognizes the comments by the delimiters (`/**` and `*/` in this case), you don't
227*need* to provide any commands for a comment to be valid; just a description text is fine.
228
229To describe a class, use the same construct above the class definition:
230```c++
231/**
232 * Alerts are for notifying old versions if they become too obsolete and
233 * need to upgrade. The message is displayed in the status bar.
234 * @see GetWarnings()
235 */
236class CAlert
237```
238
239To describe a member or variable, place the comment on the line(s) before it, using `/**` and `*/`, `//!`, or `///`:
240```c++
241//! Description before the member
242int var;
243```
244
245Avoid trailing (inline) member comments like `int var; //!< Description after the member`.
246
247  - *Rationale*: Forgetting the `<` silently breaks Doxygen output.
248
249Also OK:
250```c++