From 370120ec2ff4b5e7d5cd6678a7be7cfe651be509 Mon Sep 17 00:00:00 2001 From: Jon Atack Date: Fri, 6 May 2022 18:09:21 +0200 Subject: Remove obsolete BDB ENABLE_WALLET section in developer notes --- doc/developer-notes.md | 4 ---- 1 file changed, 4 deletions(-) diff --git a/doc/developer-notes.md b/doc/developer-notes.md index 9b1026a375..b1bb7dc887 100644 --- a/doc/developer-notes.md +++ b/doc/developer-notes.md @@ -657,10 +657,6 @@ Wallet - Make sure that no crashes happen with run-time option `-disablewallet`. -- Include `db_cxx.h` (BerkeleyDB header) only when `ENABLE_WALLET` is set. - - - *Rationale*: Otherwise compilation of the disable-wallet build will fail in environments without BerkeleyDB. - General C++ ------------- -- cgit v1.2.3 From fc4cb857ccfa622e76f0f8e7aa164ca4d8bd599a Mon Sep 17 00:00:00 2001 From: Jon Atack Date: Fri, 6 May 2022 18:15:57 +0200 Subject: Prefer Python for scripts in developer notes along with a few miscellaneous touch-ups. --- doc/developer-notes.md | 8 +++++--- 1 file changed, 5 insertions(+), 3 deletions(-) diff --git a/doc/developer-notes.md b/doc/developer-notes.md index b1bb7dc887..00fa0825a8 100644 --- a/doc/developer-notes.md +++ b/doc/developer-notes.md @@ -859,12 +859,12 @@ from using a different variable with the same name), please name variables so that their names do not shadow variables defined in the source code. When using nested cycles, do not name the inner cycle variable the same as in -the upper cycle, etc. +the outer cycle, etc. Threads and synchronization ---------------------------- -- Prefer `Mutex` type to `RecursiveMutex` one +- Prefer `Mutex` type to `RecursiveMutex` one. - Consistently use [Clang Thread Safety Analysis](https://clang.llvm.org/docs/ThreadSafetyAnalysis.html) annotations to get compile-time warnings about potential race conditions in code. Combine annotations in function declarations with @@ -943,6 +943,8 @@ TRY_LOCK(cs_vNodes, lockNodes); Scripts -------------------------- +Write scripts in Python rather than bash, when possible. + ### Shebang - Use `#!/usr/bin/env bash` instead of obsolete `#!/bin/bash`. @@ -1386,7 +1388,7 @@ communication: ``` - For consistency and friendliness to code generation tools, interface method - input and inout parameters should be ordered first and output parameters + input and in-out parameters should be ordered first and output parameters should come last. Example: -- cgit v1.2.3 From 5fca70f5b16fee4a732a1d7fd3fb1c7e775decdf Mon Sep 17 00:00:00 2001 From: Jon Atack Date: Fri, 6 May 2022 18:29:18 +0200 Subject: Link in developer notes style to internal interface exception --- doc/developer-notes.md | 7 ++++++- 1 file changed, 6 insertions(+), 1 deletion(-) diff --git a/doc/developer-notes.md b/doc/developer-notes.md index 00fa0825a8..ab2a899dd7 100644 --- a/doc/developer-notes.md +++ b/doc/developer-notes.md @@ -96,7 +96,10 @@ code. Guidelines](https://isocpp.github.io/CppCoreGuidelines/CppCoreGuidelines#Renum-caps), which recommend using `snake_case`. Please use what seems appropriate. - Class names, function names, and method names are UpperCamelCase - (PascalCase). Do not prefix class names with `C`. + (PascalCase). Do not prefix class names with `C`. See [Internal interface + naming style](#internal-interface-naming-style) for an exception to this + convention. + - Test suite naming convention: The Boost test suite in file `src/test/foo_tests.cpp` should be named `foo_tests`. Test suite names must be unique. @@ -1416,6 +1419,8 @@ communication: virtual bool disconnect(NodeId id) = 0; ``` +### Internal interface naming style + - For consistency and friendliness to code generation tools, interface method names should be `lowerCamelCase` and standalone function names should be `UpperCamelCase`. -- cgit v1.2.3 From e66b321fd1ddfffd9bfc59d407ad8f03490b873c Mon Sep 17 00:00:00 2001 From: Jon Atack Date: Mon, 9 May 2022 17:35:15 +0200 Subject: Add C++ functions and methods section to developer notes Credit for some parts to the Google C++ Style Guide "Inputs and Outputs" section at https://google.github.io/styleguide/cppguide.html#Inputs_and_Outputs Co-authored-by: laanwj <126646+laanwj@users.noreply.github.com> --- doc/developer-notes.md | 43 ++++++++++++++++++++++++++----------------- 1 file changed, 26 insertions(+), 17 deletions(-) diff --git a/doc/developer-notes.md b/doc/developer-notes.md index ab2a899dd7..ef40265818 100644 --- a/doc/developer-notes.md +++ b/doc/developer-notes.md @@ -141,6 +141,27 @@ public: } // namespace foo ``` +Coding Style (C++ functions and methods) +-------------------- + +- When ordering function parameters, place input parameters first, then any + in-out parameters, followed by any output parameters. + +- *Rationale*: API consistency. + +- Prefer returning values directly to using in-out or output parameters. Use + `std::optional` where helpful for returning values. + +- *Rationale*: Less error-prone (no need for assumptions about what the output + is initialized to on failure), easier to read, and often the same or better + performance. + +- Generally, use `std::optional` to represent optional by-value inputs (and + instead of a magic default value, if there is no real default). Non-optional + input parameters should usually be values or const references, while + non-optional in-out and output parameters should usually be references, as + they cannot be null. + Coding Style (C++ named arguments) ------------------------------ @@ -1390,22 +1411,9 @@ communication: virtual boost::signals2::scoped_connection connectTipChanged(TipChangedFn fn) = 0; ``` -- For consistency and friendliness to code generation tools, interface method - input and in-out parameters should be ordered first and output parameters - should come last. +- Interface methods should not be overloaded. - Example: - - ```c++ - // Good: error output param is last - virtual bool broadcastTransaction(const CTransactionRef& tx, CAmount max_fee, std::string& error) = 0; - - // Bad: error output param is between input params - virtual bool broadcastTransaction(const CTransactionRef& tx, std::string& error, CAmount max_fee) = 0; - ``` - -- For friendliness to code generation tools, interface methods should not be - overloaded: + *Rationale*: consistency and friendliness to code generation tools. Example: @@ -1421,10 +1429,11 @@ communication: ### Internal interface naming style -- For consistency and friendliness to code generation tools, interface method - names should be `lowerCamelCase` and standalone function names should be +- Interface method names should be `lowerCamelCase` and standalone function names should be `UpperCamelCase`. + *Rationale*: consistency and friendliness to code generation tools. + Examples: ```c++ -- cgit v1.2.3 From 654284209f30fd309c326a527cda1d2d7385cee8 Mon Sep 17 00:00:00 2001 From: Jon Atack Date: Tue, 10 May 2022 16:29:15 +0200 Subject: Add clang lifetimebound section to developer notes --- doc/developer-notes.md | 11 +++++++++++ 1 file changed, 11 insertions(+) diff --git a/doc/developer-notes.md b/doc/developer-notes.md index ef40265818..ddbbd0709b 100644 --- a/doc/developer-notes.md +++ b/doc/developer-notes.md @@ -32,6 +32,7 @@ Developer Notes - [C++ data structures](#c-data-structures) - [Strings and formatting](#strings-and-formatting) - [Shadowing](#shadowing) + - [Lifetimebound](#lifetimebound) - [Threads and synchronization](#threads-and-synchronization) - [Scripts](#scripts) - [Shebang](#shebang) @@ -885,6 +886,16 @@ please name variables so that their names do not shadow variables defined in the When using nested cycles, do not name the inner cycle variable the same as in the outer cycle, etc. +Lifetimebound +-------------- + +The [Clang `lifetimebound` +attribute](https://clang.llvm.org/docs/AttributeReference.html#lifetimebound) +can be used to tell the compiler that a lifetime is bound to an object and +potentially see a compile-time warning if the object has a shorter lifetime from +the invalid use of a temporary. You can use the attribute by adding a `LIFETIMEBOUND` +annotation defined in `src/attributes.h`; please grep the codebase for examples. + Threads and synchronization ---------------------------- -- cgit v1.2.3