Coding Style - Bitcoin Core

Indentation and Whitespace

Bitcoin Core follows the rules specified in src/.clang-format. Use the clang-format-diff script to automatically clean up patches.

Key Rules

Braces on new lines for classes, functions, methods
Braces on same line for everything else (including structs)
4 space indentation (no tabs) for every block except namespaces
No indentation for public/protected/private or for namespace
No extra spaces inside parentheses; don’t do ( this )
No space after function names; one space after if, for, and while
Single-statement if: Can appear on same line without braces; otherwise braces required
Line width: No hard limit, but prefer less than 100 characters if it doesn’t decrease readability

Example

int g_count{0};

namespace foo {
class Class
{
    std::string m_name;

public:
    bool Function(const std::string& s, int n)
    {
        // Comment summarising what this section of code does
        for (int i = 0; i < n; ++i) {
            int total_sum{0};
            // When something fails, return early
            if (!Something()) return false;
            ...
            if (SomethingElse(i)) {
                total_sum += ComputeSomething(g_count);
            } else {
                DoSomething(m_name, total_sum);
            }
        }

        // Success return is usually at the end
        return true;
    }
}
} // namespace foo

Naming Conventions

These are preferred in new code but not required when changes would affect significant existing code.

Variables and Namespaces

Variable names: All lowercase, may use _ to separate words (snake_case)
Function arguments: Same as variables
Class member variables: m_ prefix (e.g., m_name, m_count)
Global variables: g_ prefix (e.g., g_context)

Constants and Enums

Constant names: All uppercase, use _ to separate words (e.g., MAX_BLOCK_SIZE)
Enumerator constants: May be snake_case, PascalCase, or ALL_CAPS (use what seems appropriate)

Classes and Functions

Class names: UpperCamelCase (PascalCase), do NOT prefix with C
Function names: UpperCamelCase (PascalCase)
Method names: UpperCamelCase (PascalCase)

Test Suites

Boost test suite in src/test/foo_tests.cpp should be named foo_tests. Test suite names must be unique.

C++ Best Practices

Preferred Syntax

Increment: Prefer ++i over i++
Null pointers: Use nullptr (not NULL or (void*)0)
Compile-time checks: Use static_assert over assert where possible
Casts: Use named/functional casts, not C-style casts
- Between integer types: int(x) or int{x} (not (int) x)
- Between complex types: static_cast, reinterpret_cast, const_cast
Initialization: Prefer list initialization int x{0}; over int x = 0; or int x(0);
Recursion: Must be explicit with NOLINTNEXTLINE(misc-no-recursion) comment

Namespace Usage

For function calls, specify namespace explicitly to avoid argument-dependent lookup (ADL):

#include <filesystem>

namespace fs {
class path : public std::filesystem::path {};
bool exists(const fs::path& p) = delete;
}

int main()
{
    std::filesystem::path p;
    exists(p); // ADL being used - may call unintended function
}

Functions and Methods

Parameter Ordering

When ordering function parameters:

Input parameters first
In-out parameters next
Output parameters last

Rationale: API consistency

Return Values

Prefer returning values directly over using in-out/output parameters
Use std::optional for optional return values
Use std::optional for optional by-value inputs (instead of magic default values)
Non-optional input parameters: Usually values or const references
Non-optional in-out/output parameters: Usually references (cannot be null)

Returning values directly is less error-prone, easier to read, and often has the same or better performance.

Named Arguments

Use a format that clang-tidy understands:

void function(Addrman& addrman, bool clear);

int main()
{
    function(g_addrman, /*clear=*/false);
}

Running clang-tidy

Install dependencies (Ubuntu/Debian):

apt install clang-tidy clang

Configure with clang:

cmake -B build -DCMAKE_C_COMPILER=clang -DCMAKE_CXX_COMPILER=clang++ \
    -DCMAKE_EXPORT_COMPILE_COMMANDS=ON

Run on all files:

( cd ./src/ && run-clang-tidy -p ../build -j $(nproc) )

Run on changed lines only:

git diff | ( cd ./src/ && clang-tidy-diff -p2 -path ../build -j $(nproc) )

Doxygen Comments

Use Doxygen-compatible comments for functions, methods, and fields.

Function Documentation

/**
 * ... Description ...
 *
 * @param[in]  arg1 input description...
 * @param[in]  arg2 input description...
 * @param[out] arg3 output description...
 * @return Return cases...
 * @throws Error type and cases...
 * @pre  Pre-condition for function...
 * @post Post-condition for function...
 */
bool function(int arg1, const char *arg2, std::string& arg3)

Class Documentation

/**
 * Alerts are for notifying old versions if they become too obsolete and
 * need to upgrade. The message is displayed in the status bar.
 * @see GetWarnings()
 */
class CAlert

Member/Variable Documentation

//! Description before the member
int var;

int var; //!< Description after the member

Recommendations

Avoid duplicating type and input/output information in descriptions
Use backticks to refer to argument names
Doxygen automatically builds hyperlinks for known functions
Avoid linking to external documentation (links can break)
Use // or /* */ for comments you want preserved in code previews

Data Structures

std::map Usage

Never use std::map[] syntax when reading from a map. Use .find() instead. [] performs an insert if the key doesn’t exist, which has caused memory leaks and race conditions.

Using [] is fine for writing to a map.

Iterator Safety

Do not compare an iterator from one data structure with an iterator from another, even if they’re the same type. Rationale: Undefined behavior that has caused hard-to-debug crashes.

Vector Safety

Watch out for out-of-bounds access
&vch[vch.size()] is illegal, including &vch[0] for empty vectors
Use vch.data() and vch.data() + vch.size() instead
Vector bounds checking is only enabled in debug mode

Member Initialization

Initialize all non-static class members where they are defined:

class A
{
    uint32_t m_count{0};
}

Rationale: Ensures determinism, helps static analyzers, makes uninitialized members easy to spot.

Constructors

By default, declare constructors explicit: Rationale: Prevents unintended conversions.

Character Types

Use explicitly signed or unsigned chars, or better yet uint8_t and int8_t. Don’t use bare char unless passing to third-party API. Rationale: char signedness is architecture-dependent, which can lead to interoperability problems or dangerous conditions like out-of-bounds array access.

std::span

Use std::span as a function argument when it can operate on any range-like container:

void Foo(std::span<const int> data);

std::vector<int> vec{1,2,3};
Foo(vec);

Rationale: Avoids potentially expensive conversion to vector if caller has data in another container type.

Enumerations

Prefer enum class (scoped) over enum (traditional): Rationale: Avoids implicit conversions to int and name clashes from enumerators exported to surrounding scope.

enum class Tabs {
    info,
    console,
    network_graph,
    peers
};

int GetInt(Tabs tab)
{
    switch (tab) {
    case Tabs::info: return 0;
    case Tabs::console: return 1;
    case Tabs::network_graph: return 2;
    case Tabs::peers: return 3;
    } // no default case, so the compiler can warn about missing cases
    assert(false);
}

Strings and Formatting

String Handling

Use std::string, avoid C string manipulation functions
Rationale: Safer, less scope for buffer overflows, no surprises with \0 characters

Format Specifiers

For strprintf, LogInfo, LogDebug, etc., don’t use size specifiers (hh, h, l, ll, j, z, t, L) for arithmetic types. Rationale: Bitcoin Core uses tinyformat, which is type safe.

Using .c_str()

Use .c_str() sparingly - only to pass C++ strings to C functions expecting NULL-terminated strings.

Don’t use with .size() - use .data() instead
Don’t use with tfm::format, strprintf, LogInfo, LogDebug - they handle strings
Don’t use to convert to QString - use QString::fromStdString()
When you do use it, consider checking for embedded '\0' characters that could truncate the string

Threading and Synchronization

Mutex Preference

Prefer Mutex type to RecursiveMutex.

Thread Safety Analysis

Consistently use Clang Thread Safety Analysis annotations:

// txmempool.h
class CTxMemPool
{
public:
    mutable RecursiveMutex cs;
    void UpdateTransactionsFromBlock(...) 
        EXCLUSIVE_LOCKS_REQUIRED(::cs_main, cs);
}

// txmempool.cpp
void CTxMemPool::UpdateTransactionsFromBlock(...)
{
    AssertLockHeld(::cs_main);
    AssertLockHeld(cs);
    ...
}

Add annotations exclusively to function declarations, not definitions. Combine annotations in declarations with run-time asserts in definitions.

Lock Scope

When using LOCK/TRY_LOCK, surround the statement and code needing the lock with braces:

// OK
{
    TRY_LOCK(cs_vNodes, lockNodes);
    ...
}

// Wrong
TRY_LOCK(cs_vNodes, lockNodes);
{
    ...
}

Source Code Organization

Implementation Location

Implementation code should go in .cpp files, not .h, unless:

Necessary due to template usage
Performance due to inlining is critical

Rationale: Shorter, simpler headers are easier to read and reduce compile time.

Header Includes

Every .cpp and .h file should #include every header it directly uses, even if already indirectly included. Rationale: Prevents compilation failures when indirect dependencies change; makes real dependencies clear.

Namespace Rules

Don’t import into global namespace (using namespace ...)
Use fully specified types like std::string
Terminate namespaces with a comment:

namespace mynamespace {
...
} // namespace mynamespace

namespace {
...
} // namespace

Shadowing

Although -Wshadow is not enabled by default, name variables so they don’t shadow variables defined elsewhere. When using nested loops, don’t reuse the inner loop variable name.

Python Style

Refer to /test/functional/README.md#style-guidelines for Python coding style.

Architecture

Developer Guides

Contributing

Advanced Topics

​Indentation and Whitespace

​Key Rules

​Example

​Naming Conventions

​Variables and Namespaces

​Constants and Enums

​Classes and Functions

​Test Suites

​C++ Best Practices

​Preferred Syntax

​Namespace Usage

​Functions and Methods

​Parameter Ordering

​Return Values

​Named Arguments

​Running clang-tidy

​Doxygen Comments

​Function Documentation

​Class Documentation

​Member/Variable Documentation

​Recommendations

​Data Structures

​std::map Usage

​Iterator Safety

​Vector Safety

​Member Initialization

​Constructors

​Character Types

​std::span

​Enumerations

​Strings and Formatting

​String Handling

​Format Specifiers

​Using .c_str()

​Threading and Synchronization

​Mutex Preference

​Thread Safety Analysis

​Lock Scope

​Source Code Organization

​Implementation Location

​Header Includes

​Namespace Rules

​Shadowing

​Python Style

Indentation and Whitespace

Key Rules

Example

Naming Conventions

Variables and Namespaces

Constants and Enums

Classes and Functions

Test Suites

C++ Best Practices

Preferred Syntax

Namespace Usage

Functions and Methods

Parameter Ordering

Return Values

Named Arguments

Running clang-tidy

Doxygen Comments

Function Documentation

Class Documentation

Member/Variable Documentation

Recommendations

Data Structures

std::map Usage

Iterator Safety

Vector Safety

Member Initialization

Constructors

Character Types

std::span

Enumerations

Strings and Formatting

String Handling

Format Specifiers

Using .c_str()

Threading and Synchronization

Mutex Preference

Thread Safety Analysis

Lock Scope

Source Code Organization

Implementation Location

Header Includes

Namespace Rules

Shadowing

Python Style