aboutsummaryrefslogtreecommitdiff
path: root/doc/coding.md
diff options
context:
space:
mode:
authorMichael Ford <fanquake@gmail.com>2014-12-13 12:35:39 +0800
committerMichael Ford <fanquake@gmail.com>2014-12-19 10:58:56 +0800
commit3bf5f52808a5f7cd3958c9eea273d99fd11417ca (patch)
treedc053e87cacd006447f2047f409bbf434121aa2d /doc/coding.md
parent4444b879bc1da56fffa4cb4cf31a276a795f43b9 (diff)
Create developer-notes.md
Moves coding guidelines and development tips/tricks into a single file. Also adds a section explaining pull request terminology.
Diffstat (limited to 'doc/coding.md')
-rw-r--r--doc/coding.md138
1 files changed, 0 insertions, 138 deletions
diff --git a/doc/coding.md b/doc/coding.md
deleted file mode 100644
index 43294dbe4c..0000000000
--- a/doc/coding.md
+++ /dev/null
@@ -1,138 +0,0 @@
-Coding
-====================
-
-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.
-
-Block style example:
-```c++
-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:
-```c++
-/**
- * ... 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 http://www.stack.nl/~dimitri/doxygen/manual/commands.html.
-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:
-```c++
-/**
- * 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:
-```c++
-int var; //!< Detailed description after the member
-```
-
-Also OK:
-```c++
-///
-/// ... text ...
-///
-bool function2(int arg1, const char *arg2)
-```
-
-Not OK (used plenty in the current source, but not picked up):
-```c++
-//
-// ... text ...
-//
-```
-
-A full list of comment syntaxes picked up by doxygen can be found at http://www.stack.nl/~dimitri/doxygen/manual/docblocks.html,
-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).
-
-Threads
--------
-
-- ThreadScriptCheck : Verifies block scripts.
-
-- ThreadImport : Loads blocks from blk*.dat files or bootstrap.dat.
-
-- StartNode : Starts other threads.
-
-- 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.