sikkienl/dash
1
0
Fork 0
mirror of https://github.com/dashpay/dash.git synced 2024-12-26 04:22:55 +01:00
Code Issues Actions Packages Projects Releases Wiki Activity

Merge #17539: doc: Update and improve Developer Notes

Browse Source 
794fe91395c79f46a6d920bc08de5a0551b359a3 doc: Update and improve Developer Notes (Hennadii Stepanov)

Pull request description:

  This PR:
  - removes outdated things, e.g., global pointer `pwalletMain` etc
  - adds "Sanitizers" to the TOC
  - makes filenames, `peer.dat` and `debug.log`, monospaced
  - specifies that _compile-time_ constant names are all uppercase
  - rewords using `explicit` with constructors

ACKs for top commit:
  jamesob:
    lazy ACK 794fe91395
  practicalswift:
    ACK 794fe91395c79f46a6d920bc08de5a0551b359a3 -- nice improvements!

Tree-SHA512: 2c5f035b1627f5fac8dc2453199d9e46bd101f86771de567cd95698de3c61cc459444ec1a68710e1d280195e1e40b42d9f40906297d12f12bf37749eca58297d
This commit is contained in:
fanquake 2019-11-23 11:16:46 -05:00 committed by Pasta
parent af9cf0534b
commit d202707939
No known key found for this signature in database
GPG Key ID: 52527BEDABE87984
1 changed files with 16 additions and 24 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

40
doc/developer-notes.md
View File

@ -12,12 +12,13 @@ Developer Notes
- [Development tips and tricks](#development-tips-and-tricks) - [Development tips and tricks](#development-tips-and-tricks)
- [Compiling for debugging](#compiling-for-debugging) - [Compiling for debugging](#compiling-for-debugging)
- [Compiling for gprof profiling](#compiling-for-gprof-profiling) - [Compiling for gprof profiling](#compiling-for-gprof-profiling)
- [debug.log](#debuglog) - [`debug.log`](#debuglog)
- [Testnet and Regtest modes](#testnet-and-regtest-modes) - [Testnet and Regtest modes](#testnet-and-regtest-modes)
- [DEBUG_LOCKORDER](#debug_lockorder) - [DEBUG_LOCKORDER](#debug_lockorder)
- [Valgrind suppressions file](#valgrind-suppressions-file) - [Valgrind suppressions file](#valgrind-suppressions-file)
- [Compiling for test coverage](#compiling-for-test-coverage) - [Compiling for test coverage](#compiling-for-test-coverage)
- [Performance profiling with perf](#performance-profiling-with-perf) - [Performance profiling with perf](#performance-profiling-with-perf)
- [Sanitizers](#sanitizers)
- [Locking/mutex usage notes](#lockingmutex-usage-notes) - [Locking/mutex usage notes](#lockingmutex-usage-notes)
- [Threads](#threads) - [Threads](#threads)
- [Ignoring IDE/editor files](#ignoring-ideeditor-files) - [Ignoring IDE/editor files](#ignoring-ideeditor-files)
@ -63,7 +64,7 @@ tool to clean up patches automatically before submission.
- Braces on the same line for everything else. - Braces on the same line for everything else.
- 4 space indentation (no tabs) for every block except namespaces. - 4 space indentation (no tabs) for every block except namespaces.
- No indentation for `public`/`protected`/`private` or for `namespace`. - No indentation for `public`/`protected`/`private` or for `namespace`.
- No extra spaces inside parenthesis; don't do ( this ). - No extra spaces inside parenthesis; don't do `( this )`.
- No space after function names; one space after `if`, `for` and `while`. - No space after function names; one space after `if`, `for` and `while`.
- If an `if` only has a single-statement `then`-clause, it can appear - If an `if` only has a single-statement `then`-clause, it can appear
on the same line as the `if`, without braces. In every other case, on the same line as the `if`, without braces. In every other case,
@ -82,7 +83,7 @@ code.
separate words (snake_case). separate words (snake_case).
- Class member variables have a `m_` prefix. - Class member variables have a `m_` prefix.
- Global variables have a `g_` prefix. - Global variables have a `g_` prefix.
- Constant names are all uppercase, and use `_` to separate words. - Compile-time constant names are all uppercase, and use `_` to separate words.
- Class names, function names, and method names are UpperCamelCase - 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`.
- Test suite naming convention: The Boost test suite in file - Test suite naming convention: The Boost test suite in file
@ -215,15 +216,15 @@ produce better debugging builds.
Run configure with the `--enable-gprof` option, then make. Run configure with the `--enable-gprof` option, then make.
### debug.log ### `debug.log`
If the code is behaving strangely, take a look in the debug.log file in the data directory; 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. error and debugging messages are written there.
The `-debug=...` command-line option controls debugging; running with just `-debug` or `-debug=1` will turn The `-debug=...` command-line option controls debugging; running with just `-debug` or `-debug=1` will turn
on all categories (and give you a very large debug.log file). on all categories (and give you a very large `debug.log` file).
The Qt code routes `qDebug()` output to debug.log under category "qt": run with `-debug=qt` The Qt code routes `qDebug()` output to `debug.log` under category "qt": run with `-debug=qt`
to see it. to see it.
### Testnet and Regtest modes ### Testnet and Regtest modes
@ -241,7 +242,7 @@ Dash Core is a multi-threaded application, and deadlocks or other
multi-threading bugs can be very difficult to track down. The `--enable-debug` multi-threading bugs can be very difficult to track down. The `--enable-debug`
configure option adds `-DDEBUG_LOCKORDER` to the compiler flags. This inserts configure option adds `-DDEBUG_LOCKORDER` to the compiler flags. This inserts
run-time checks to keep track of which locks are held and adds warnings to the run-time checks to keep track of which locks are held and adds warnings to the
debug.log file if inconsistencies are detected. `debug.log` file if inconsistencies are detected.
### Valgrind suppressions file ### Valgrind suppressions file
@ -283,8 +284,7 @@ the functional test framework. Perf can observe a running process and sample
(at some frequency) where its execution is. (at some frequency) where its execution is.
Perf installation is contingent on which kernel version you're running; see Perf installation is contingent on which kernel version you're running; see
[this StackExchange [this thread](https://askubuntu.com/questions/50145/how-to-install-perf-monitoring-tool)
thread](https://askubuntu.com/questions/50145/how-to-install-perf-monitoring-tool)
for specific instructions. for specific instructions.
Certain kernel parameters may need to be set for perf to be able to inspect the Certain kernel parameters may need to be set for perf to be able to inspect the
@ -319,7 +319,7 @@ or using a graphical tool like [Hotspot](https://github.com/KDAB/hotspot).
See the functional test documentation for how to invoke perf within tests. See the functional test documentation for how to invoke perf within tests.
**Sanitizers** ### Sanitizers
Dash Core can be compiled with various "sanitizers" enabled, which add Dash Core can be compiled with various "sanitizers" enabled, which add
instrumentation for issues regarding things like memory safety, thread race instrumentation for issues regarding things like memory safety, thread race
@ -380,7 +380,7 @@ 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 `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 as each waits for the other to release its lock) are a problem. Compile with
`-DDEBUG_LOCKORDER` (or use `--enable-debug`) to get lock order inconsistencies `-DDEBUG_LOCKORDER` (or use `--enable-debug`) to get lock order inconsistencies
reported in the debug.log file. reported in the `debug.log` file.
Re-architecting the core code so there are better-defined interfaces Re-architecting the core code so there are better-defined interfaces
between the various components is a goal, with any necessary locking between the various components is a goal, with any necessary locking
@ -394,8 +394,6 @@ Threads
- ThreadImport : Loads blocks from blk*.dat files or bootstrap.dat. - ThreadImport : Loads blocks from blk*.dat files or bootstrap.dat.
- StartNode : Starts other threads.
- ThreadDNSAddressSeed : Loads addresses of peers from the DNS. - ThreadDNSAddressSeed : Loads addresses of peers from the DNS.
- ThreadMapPort : Universal plug-and-play startup/shutdown. - ThreadMapPort : Universal plug-and-play startup/shutdown.
@ -410,7 +408,7 @@ Threads
- ThreadMessageHandler : Higher-level message handling (sending and receiving). - ThreadMessageHandler : Higher-level message handling (sending and receiving).
- DumpAddresses : Dumps IP addresses of nodes to peers.dat. - DumpAddresses : Dumps IP addresses of nodes to `peers.dat`.
- ThreadRPCServer : Remote procedure call handler, listens on port 9998 for connections and services them. - ThreadRPCServer : Remote procedure call handler, listens on port 9998 for connections and services them.
@ -487,11 +485,6 @@ Wallet
- Make sure that no crashes happen with run-time option `-disablewallet`. - Make sure that no crashes happen with run-time option `-disablewallet`.
- *Rationale*: In RPC code that conditionally uses the wallet (such as
`validateaddress`), it is easy to forget that global pointer `pwalletMain`
can be nullptr. See `test/functional/disablewallet.py` for functional tests
exercising the API with `-disablewallet`.
- Include `db_cxx.h` (BerkeleyDB header) only when `ENABLE_WALLET` is set. - 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. - *Rationale*: Otherwise compilation of the disable-wallet build will fail in environments without BerkeleyDB.
@ -566,11 +559,10 @@ class A
} }
``` ```
- By default, declare single-argument constructors `explicit`. - By default, declare constructors `explicit`.
- *Rationale*: This is a precaution to avoid unintended conversions that might - *Rationale*: This is a precaution to avoid unintended
arise when single-argument constructors are used as implicit conversion [conversions](https://en.cppreference.com/w/cpp/language/converting_constructor).
functions.
- Use explicitly signed or unsigned `char`s, or even better `uint8_t` and - Use explicitly signed or unsigned `char`s, or even better `uint8_t` and
`int8_t`. Do not use bare `char` unless it is to pass to a third-party API. `int8_t`. Do not use bare `char` unless it is to pass to a third-party API.