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.

coding.md 4.6KB

123456789101112131415161718192021222324252627282930313233343536373839404142434445464748495051525354555657585960616263646566676869707172737475767778798081828384858687888990919293949596979899100101102103104105106107108109110111112113114115116117118119120121122123124125126127128129130131132133134135136137138139140141142143144145146147148149150151152153154
  1. Coding
  2. ====================
  3. Various coding styles have been used during the history of the codebase,
  4. and the result is not very consistent. However, we're now trying to converge to
  5. a single style, so please use it in new code. Old code will be converted
  6. gradually.
  7. - Basic rules specified in src/.clang-format. Use a recent clang-format-3.5 to format automatically.
  8. - Braces on new lines for namespaces, classes, functions, methods.
  9. - Braces on the same line for everything else.
  10. - 4 space indentation (no tabs) for every block except namespaces.
  11. - No indentation for public/protected/private or for namespaces.
  12. - No extra spaces inside parenthesis; don't do ( this )
  13. - No space after function names; one space after if, for and while.
  14. - Includes need to be ordered alphabetically, separate own and foreign headers with a new-line (example key.cpp):
  15. ```c++
  16. #include "key.h"
  17. #include "crypto/sha2.h"
  18. #include "util.h"
  19. #include <openssl/foo.h>
  20. ```
  21. - Class or struct keywords in header files need to be ordered alphabetically:
  22. ```c++
  23. class CAlpha;
  24. class CBeta;
  25. ```
  26. Block style example:
  27. ```c++
  28. namespace foo
  29. {
  30. class Class
  31. {
  32. bool Function(char* psz, int n)
  33. {
  34. // Comment summarising what this section of code does
  35. for (int i = 0; i < n; i++) {
  36. // When something fails, return early
  37. if (!Something())
  38. return false;
  39. ...
  40. }
  41. // Success return is usually at the end
  42. return true;
  43. }
  44. }
  45. }
  46. ```
  47. Doxygen comments
  48. -----------------
  49. To facilitate the generation of documentation, use doxygen-compatible comment blocks for functions, methods and fields.
  50. For example, to describe a function use:
  51. ```c++
  52. /**
  53. * ... text ...
  54. * @param[in] arg1 A description
  55. * @param[in] arg2 Another argument description
  56. * @pre Precondition for function...
  57. */
  58. bool function(int arg1, const char *arg2)
  59. ```
  60. A complete list of `@xxx` commands can be found at http://www.stack.nl/~dimitri/doxygen/manual/commands.html.
  61. As Doxygen recognizes the comments by the delimiters (`/**` and `*/` in this case), you don't
  62. *need* to provide any commands for a comment to be valid, just a description text is fine.
  63. To describe a class use the same construct above the class definition:
  64. ```c++
  65. /**
  66. * Alerts are for notifying old versions if they become too obsolete and
  67. * need to upgrade. The message is displayed in the status bar.
  68. * @see GetWarnings()
  69. */
  70. class CAlert
  71. {
  72. ```
  73. To describe a member or variable use:
  74. ```c++
  75. int var; //!< Detailed description after the member
  76. ```
  77. Also OK:
  78. ```c++
  79. ///
  80. /// ... text ...
  81. ///
  82. bool function2(int arg1, const char *arg2)
  83. ```
  84. Not OK (used plenty in the current source, but not picked up):
  85. ```c++
  86. //
  87. // ... text ...
  88. //
  89. ```
  90. A full list of comment syntaxes picked up by doxygen can be found at http://www.stack.nl/~dimitri/doxygen/manual/docblocks.html,
  91. but if possible use one of the above styles.
  92. Locking/mutex usage notes
  93. -------------------------
  94. The code is multi-threaded, and uses mutexes and the
  95. LOCK/TRY_LOCK macros to protect data structures.
  96. Deadlocks due to inconsistent lock ordering (thread 1 locks cs_main
  97. and then cs_wallet, while thread 2 locks them in the opposite order:
  98. result, deadlock as each waits for the other to release its lock) are
  99. a problem. Compile with -DDEBUG_LOCKORDER to get lock order
  100. inconsistencies reported in the debug.log file.
  101. Re-architecting the core code so there are better-defined interfaces
  102. between the various components is a goal, with any necessary locking
  103. done by the components (e.g. see the self-contained CKeyStore class
  104. and its cs_KeyStore lock for example).
  105. Threads
  106. -------
  107. - ThreadScriptCheck : Verifies block scripts.
  108. - ThreadImport : Loads blocks from blk*.dat files or bootstrap.dat.
  109. - StartNode : Starts other threads.
  110. - ThreadGetMyExternalIP : Determines outside-the-firewall IP address, sends addr message to connected peers when it determines it.
  111. - ThreadDNSAddressSeed : Loads addresses of peers from the DNS.
  112. - ThreadMapPort : Universal plug-and-play startup/shutdown
  113. - ThreadSocketHandler : Sends/Receives data from peers on port 8333.
  114. - ThreadOpenAddedConnections : Opens network connections to added nodes.
  115. - ThreadOpenConnections : Initiates new connections to peers.
  116. - ThreadMessageHandler : Higher-level message handling (sending and receiving).
  117. - DumpAddresses : Dumps IP addresses of nodes to peers.dat.
  118. - ThreadFlushWalletDB : Close the wallet.dat file if it hasn't been used in 500ms.
  119. - ThreadRPCServer : Remote procedure call handler, listens on port 8332 for connections and services them.
  120. - BitcoinMiner : Generates bitcoins (if wallet is enabled).
  121. - Shutdown : Does an orderly shutdown of everything.