1 files changed, 48 insertions, 41 deletions
diff --git a/doc/coding.md b/doc/coding.md
index 69388c9ce2..ceed8c18b4 100644
--- a/doc/coding.md
+++ b/doc/coding.md
@@ -1,47 +1,54 @@
 Coding
 ====================
 
-Please be consistent with the existing coding style.
-
-Block style:
-
-	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;
-	}
-
-- ANSI/Allman block style
-- 4 space indenting, no tabs
-- No extra spaces inside parenthesis; please don't do ( this )
-- No space after function names, one space after if, for and while
-
-Variable names begin with the type in lowercase, like nSomeVariable.
-Please don't put the first word of the variable name in lowercase like
-someVariable.
-
-Common types:
-
-	n       integer number: short, unsigned short, int, unsigned int, int64, uint64, sometimes char if used as a number
-	d       double, float
-	f       flag
-	hash    uint256
-	p       pointer or array, one p for each level of indirection
-	psz     pointer to null terminated string
-	str     string object
-	v       vector or similar list objects
-	map     map or multimap
-	set     set or multiset
-	bn      CBigNum
+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"
+
+#include <openssl/foo.h>
+```
+- Class or struct keywords in header files need to be ordered alphabetically:
+```c++
+class CAlpha;
+class CBeta;
+```
+
+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
 -----------------