You can not select more than 25 topics Topics must start with a letter or number, can include dashes ('-') and can be up to 35 characters long. 4.6KB


Various coding styles have been used during the history of the codebase, and the result is not very consistent. However, we’re now trying to converge to a single style, so please use it in new code. Old code will be converted gradually.

  • Basic rules specified in src/.clang-format. Use a recent clang-format-3.5 to format automatically.
    • Braces on new lines for namespaces, classes, functions, methods.
    • Braces on the same line for everything else.
    • 4 space indentation (no tabs) for every block except namespaces.
    • No indentation for public/protected/private or for namespaces.
    • No extra spaces inside parenthesis; don’t do ( this )
    • No space after function names; one space after if, for and while.
  • Includes need to be ordered alphabetically, separate own and foreign headers with a new-line (example key.cpp): ```c++

    include “key.h”

include “crypto/sha2.h”

include “util.h”


- Class or struct keywords in header files need to be ordered alphabetically:
class CAlpha;
class CBeta;

Block style example:

namespace foo
class Class
    bool Function(char* psz, int n)
        // Comment summarising what this section of code does
        for (int i = 0; i < n; i++) {
            // When something fails, return early
            if (!Something())
                return false;

        // Success return is usually at the end
        return true;

Doxygen comments

To facilitate the generation of documentation, use doxygen-compatible comment blocks for functions, methods and fields.

For example, to describe a function use:

 * ... text ...
 * @param[in] arg1    A description
 * @param[in] arg2    Another argument description
 * @pre Precondition for function...
bool function(int arg1, const char *arg2)

A complete list of @xxx commands can be found at As Doxygen recognizes the comments by the delimiters (/** and */ in this case), you don’t need to provide any commands for a comment to be valid, just a description text is fine.

To describe a class use the same construct above the class definition:

 * 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

To describe a member or variable use:

int var; //!< Detailed description after the member

Also OK:

/// ... text ...
bool function2(int arg1, const char *arg2)

Not OK (used plenty in the current source, but not picked up):

// ... text ...

A full list of comment syntaxes picked up by doxygen can be found at, but if possible use one of the above styles.

Locking/mutex usage notes

The code is multi-threaded, and uses mutexes and the LOCK/TRY_LOCK macros to protect data structures.

Deadlocks due to inconsistent lock ordering (thread 1 locks cs_main and then cs_wallet, while thread 2 locks them in the opposite order: result, deadlock as each waits for the other to release its lock) are a problem. Compile with -DDEBUG_LOCKORDER to get lock order inconsistencies reported in the debug.log file.

Re-architecting the core code so there are better-defined interfaces between the various components is a goal, with any necessary locking done by the components (e.g. see the self-contained CKeyStore class and its cs_KeyStore lock for example).


  • ThreadScriptCheck : Verifies block scripts.

  • ThreadImport : Loads blocks from blk*.dat files or bootstrap.dat.

  • StartNode : Starts other threads.

  • ThreadGetMyExternalIP : Determines outside-the-firewall IP address, sends addr message to connected peers when it determines it.

  • ThreadDNSAddressSeed : Loads addresses of peers from the DNS.

  • ThreadMapPort : Universal plug-and-play startup/shutdown

  • ThreadSocketHandler : Sends/Receives data from peers on port 8333.

  • ThreadOpenAddedConnections : Opens network connections to added nodes.

  • ThreadOpenConnections : Initiates new connections to peers.

  • ThreadMessageHandler : Higher-level message handling (sending and receiving).

  • DumpAddresses : Dumps IP addresses of nodes to peers.dat.

  • ThreadFlushWalletDB : Close the wallet.dat file if it hasn’t been used in 500ms.

  • ThreadRPCServer : Remote procedure call handler, listens on port 8332 for connections and services them.

  • BitcoinMiner : Generates bitcoins (if wallet is enabled).

  • Shutdown : Does an orderly shutdown of everything.