doc: unify developer-notes and productivity header styles

2025-08-25 20:21:32 +02:00 · 2025-07-23 00:10:47 -07:00
parent eb13718448
commit 26a3730711
2 changed files with 35 additions and 70 deletions
--- a/doc/developer-notes.md
+++ b/doc/developer-notes.md
@@ -1,5 +1,4 @@
-Developer Notes
-===============
+# Developer Notes

 <!-- markdown-toc start -->
 **Table of Contents**
@@ -49,8 +48,7 @@ Developer Notes

 <!-- markdown-toc end -->

-Coding Style (General)
----------------------
+## Coding Style (General)

 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
@@ -60,8 +58,7 @@ commits.

 Do not submit patches solely to modify the style of existing code.

-Coding Style (C++)
------------------
+## Coding Style (C++)

 - **Indentation and whitespace rules** as specified in
 [src/.clang-format](/src/.clang-format). You can use the provided
@@ -171,8 +168,7 @@ public:
 } // namespace foo
 ```

-Coding Style (C++ functions and methods)
--------------------
+### Coding Style (C++ functions and methods)

 - When ordering function parameters, place input parameters first, then any
  in-out parameters, followed by any output parameters.
@@ -192,8 +188,7 @@ Coding Style (C++ functions and methods)
  non-optional in-out and output parameters should usually be references, as
  they cannot be null.

-Coding Style (C++ named arguments)
------------------------------
+### Coding Style (C++ named arguments)

 When passing named arguments, use a format that clang-tidy understands. The
 argument names can otherwise not be verified by clang-tidy.
@@ -237,14 +232,11 @@ To run clang-tidy on the changed source lines:
 git diff | ( cd ./src/ && clang-tidy-diff -p2 -path ../build -j $(nproc) )
 ```

-Coding Style (Python)
---------------------
+## Coding Style (Python)

 Refer to [/test/functional/README.md#style-guidelines](/test/functional/README.md#style-guidelines).

-
-Coding Style (Doxygen-compatible comments)
------------------------------------------
+## Coding Style (Doxygen-compatible comments)

 Bitcoin Core uses [Doxygen](https://www.doxygen.nl/) to generate its official documentation.

@@ -348,8 +340,7 @@ Linux: `sudo apt install doxygen graphviz`

 MacOS: `brew install doxygen graphviz`

-Development tips and tricks
---------------------------
+## Development tips and tricks

 ### Compiling for debugging

@@ -393,7 +384,7 @@ ln -s /path/to/project/root/src src

 4. If your IDE has an option for this, change your breakpoints to use the file name only.

-### `debug.log`
+### debug.log

 If the code is behaving strangely, take a look in the `debug.log` file in the data directory;
 error and debugging messages are written there.
@@ -713,8 +704,7 @@ Additional resources:
 * [GCC Instrumentation Options](https://gcc.gnu.org/onlinedocs/gcc/Instrumentation-Options.html)
 * [Google Sanitizers Wiki](https://github.com/google/sanitizers/wiki)

-Locking/mutex usage notes
-------------------------
+## Locking/mutex usage notes

 The code is multi-threaded and uses mutexes and the
 `LOCK` and `TRY_LOCK` macros to protect data structures.
@@ -730,8 +720,7 @@ between the various components is a goal, with any necessary locking
 done by the components (e.g. see the self-contained `FillableSigningProvider` class
 and its `cs_KeyStore` lock for example).

-Threads
-------
+## Threads

 - [Main thread (`bitcoind`)](https://doxygen.bitcoincore.org/bitcoind_8cpp.html#a0ddf1224851353fc92bfbff6f499fa97)
  : Started from `main()` in `bitcoind.cpp`. Responsible for starting up and
@@ -784,22 +773,19 @@ Threads
  - [ThreadI2PAcceptIncoming (`b-i2paccept`)](https://doxygen.bitcoincore.org/class_c_connman.html#a57787b4f9ac847d24065fbb0dd6e70f8)
    : Listens for and accepts incoming I2P connections through the I2P SAM proxy.

-Development guidelines
-============================
+# Development guidelines

 A few non-style-related recommendations for developers, as well as points to
 pay attention to for reviewers of Bitcoin Core code.

-General Bitcoin Core
----------------------
+## General Bitcoin Core

 - New features should be exposed on RPC first, then can be made available in the GUI.

  - *Rationale*: RPC allows for better automatic testing. The test suite for
    the GUI is very limited.

-Logging
-------
+## Logging

 The macros `LogInfo`, `LogDebug`, `LogTrace`, `LogWarning` and `LogError` are available for
 logging messages. They should be used as follows:
@@ -837,8 +823,7 @@ Note that the format strings and parameters of `LogDebug` and `LogTrace`
 are only evaluated if the logging category is enabled, so you must be
 careful to avoid side-effects in those expressions.

-General C++
-------------
+## General C++

 For general C++ guidelines, you may refer to the [C++ Core
 Guidelines](https://isocpp.github.io/CppCoreGuidelines/).
@@ -859,8 +844,7 @@ Common misconceptions are clarified in those sections:

  - *Rationale*: This avoids memory and resource leaks, and ensures exception safety.

-C++ data structures
--------------------
+## C++ data structures

 - Never use the `std::map []` syntax when reading from a map, but instead use `.find()`.

@@ -953,8 +937,7 @@ int GetInt(Tabs tab)

 *Rationale*: The comment documents skipping `default:` label, and it complies with `clang-format` rules. The assertion prevents firing of `-Wreturn-type` warning on some compilers.

-Strings and formatting
------------------------
+## Strings and formatting

 - Use `std::string`, avoid C string manipulation functions.

@@ -988,8 +971,7 @@ Strings and formatting
    checks. If a use of strings is sensitive to this, take care to check the string for embedded NULL characters first
    and reject it if there are any.

-Shadowing
--------------
+## Shadowing

 Although the shadowing warning (`-Wshadow`) is not enabled by default (it prevents issues arising
 from using a different variable with the same name),
@@ -998,8 +980,7 @@ 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
--------------
+## Lifetimebound

 The [Clang `lifetimebound`
 attribute](https://clang.llvm.org/docs/AttributeReference.html#lifetimebound)
@@ -1008,8 +989,7 @@ 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
----------------------------
+## Threads and synchronization

 - Prefer `Mutex` type to `RecursiveMutex` one.

@@ -1110,13 +1090,11 @@ TRY_LOCK(cs_vNodes, lockNodes);
 }
 ```

-Scripts
--------------------------
+## Scripts

 Write scripts in Python or Rust rather than bash, when possible.

-Source code organization
--------------------------
+## Source code organization

 - Implementation code should go into the `.cpp` file and not the `.h`, unless necessary due to template usage or
  when performance due to inlining is critical.
@@ -1150,8 +1128,7 @@ namespace {

  - *Rationale*: Avoids confusion about the namespace context.

-GUI
-----
+## GUI

 - Do not display or manipulate dialogs in model code (classes `*Model`).

@@ -1172,8 +1149,7 @@ GUI
  - *Rationale*: Blocking the GUI thread can increase latency, and lead to
    hangs and deadlocks.

-Subtrees
----------
+## Subtrees

 Several parts of the repository are subtrees of software maintained elsewhere.

@@ -1203,8 +1179,7 @@ The ultimate upstream of the few externally managed subtrees are:
  - Used by leveldb for hardware acceleration of CRC32C checksums for data integrity.
  - Upstream at https://github.com/google/crc32c ; maintained by Google.

-Upgrading LevelDB
---------------------
+## Upgrading LevelDB

 Extra care must be taken when upgrading LevelDB. This section explains issues
 you must be aware of.
@@ -1250,8 +1225,7 @@ would be to revert the upstream fix before applying the updates to Bitcoin's
 copy of LevelDB. In general, you should be wary of any upstream changes affecting
 what data is returned from LevelDB queries.

-Scripted diffs
--------------
+## Scripted diffs

 For reformatting and refactoring commits where the changes can be easily automated using a bash script, we use
 scripted-diff commits. The bash script is included in the commit message and our CI job checks that
@@ -1307,8 +1281,7 @@ To find all previous uses of scripted diffs in the repository, do:
 git log --grep="-BEGIN VERIFY SCRIPT-"
 ```

-Release notes
-------------
+## Release notes

 Release notes should be written for any PR that:

@@ -1321,8 +1294,7 @@ Release notes should be added to a PR-specific release note file at
 `/doc/release-notes-<PR number>.md` to avoid conflicts between multiple PRs.
 All `release-notes*` files are merged into a single `release-notes-<version>.md` file prior to the release.

-RPC interface guidelines
--------------------------
+## RPC interface guidelines

 A few guidelines for introducing and reviewing new RPC interfaces:

@@ -1430,8 +1402,7 @@ A few guidelines for modifying existing RPC interfaces:

  - *Rationale*: Changes in RPC JSON structure can break downstream application compatibility. Implementation of `deprecatedrpc` provides a grace period for downstream applications to migrate. Release notes provide notification to downstream users.

-Internal interface guidelines
-----------------------------
+## Internal interface guidelines

 Internal interfaces between parts of the codebase that are meant to be
 independent (node, wallet, GUI), are defined in
--- a/doc/productivity.md
+++ b/doc/productivity.md
@@ -1,8 +1,6 @@
-Productivity Notes
-==================
+# Productivity Notes

-Table of Contents
-----------------
+## Table of Contents

 * [General](#general)
   * [Cache compilations with `ccache`](#cache-compilations-with-ccache)
@@ -23,8 +21,7 @@ Table of Contents
   * [Reference PRs easily with `refspec`s](#reference-prs-easily-with-refspecs)
   * [Diff the diffs with `git range-diff`](#diff-the-diffs-with-git-range-diff)

-General
------
+## General

 ### Cache compilations with `ccache`

@@ -114,8 +111,7 @@ This synergizes well with [`ccache`](#cache-compilations-with-ccache) as objects

 You can also set up [upstream refspecs](#reference-prs-easily-with-refspecs) to refer to pull requests easier in the above `git worktree` commands.

-Writing code
------------
+## Writing code

 ### Format C/C++ diffs with `clang-format-diff.py`

@@ -125,8 +121,7 @@ See [contrib/devtools/README.md](/contrib/devtools/README.md#clang-format-diff.p

 Usage is exactly the same as [`clang-format-diff.py`](#format-cc-diffs-with-clang-format-diffpy). You can get it [here](https://github.com/MarcoFalke/yapf-diff).

-Rebasing/Merging code
-------------
+## Rebasing/Merging code

 ### More conflict context with `merge.conflictstyle diff3`

@@ -154,8 +149,7 @@ theirs

 This may make it much clearer what caused the conflict. In this style, you can often just look at what changed between *original* and *theirs*, and mechanically apply that to *yours* (or the other way around).

-Reviewing code
--------------
+## Reviewing code

 ### Reduce mental load with `git diff` options