Correct the style of coding style

1 files changed, 163 insertions, 182 deletions

diff --git a/CODING_STYLE.md b/CODING_STYLE.md
index 2cc9ac70..3244466b 100644
--- a/CODING_STYLE.md
+++ b/CODING_STYLE.md
@@ -1,35 +1,24 @@
-0. Formatting
-
-GOLDEN RULE: Follow the style of the existing code when you make changes.
-
-a. Use tabs for leading indentation
-- tab stops are every 4 characters (only relevant for line length).
-- One indentation level -> exactly one byte (i.e. a tab character) in the source file.
-b. Line widths:
-- Lines should be at most 99 characters wide to make diff views readable and reduce merge conflicts.
-- Lines of comments should be formatted according to ease of viewing, but simplicity is to be preferred over beauty.
-c. Single-statement blocks should not have braces, unless required for clarity.
-d. Never place condition bodies on same line as condition.
-e. Space between keyword and opening parenthesis, but not following opening parenthesis or before final parenthesis.
-f. No spaces for unary operators, `->` or `.`.
-g. No space before ':' but one after it, except in the ternary operator: one on both sides.
-h. Add spaces around all other operators.
-i. Braces, when used, always have their own lines and are at same indentation level as "parent" scope.
-j. If lines are broken, a list of elements enclosed with parentheses (of any kind) and separated by a
-   separator (of any kind) are formatted such that there is exactly one element per line, followed by
-   the separator, the opening parenthesis is on the first line, followed by a line break and the closing
-   parenthesis is on a line of its own (unindented). See example below.
-
-(WRONG)
-if( a==b[ i ] ) { printf ("Hello\n"); }
-foo->bar(someLongVariableName,
-         anotherLongVariableName,
-         anotherLongVariableName,
-         anotherLongVariableName,
-         anotherLongVariableName);
-cout << "some very long string that contains completely irrelevant text that talks about this and that and contains the words \"lorem\" and \"ipsum\"" << endl;
-
-(RIGHT)
+## 0. Formatting
+
+**GOLDEN RULE**: Follow the style of the existing code when you make changes.
+
+1. Use tabs for leading indentation:
+   - tab stops are every 4 characters (only relevant for line length).
+   - one indentation level -> exactly one byte (i.e. a tab character) in the source file.
+2. Line widths:
+   - Lines should be at most 99 characters wide to make diff views readable and reduce merge conflicts.
+   - Lines of comments should be formatted according to ease of viewing, but simplicity is to be preferred over beauty.
+3. Single-statement blocks should not have braces, unless required for clarity.
+4. Never place condition bodies on same line as condition.
+5. Space between keyword and opening parenthesis, but not following opening parenthesis or before final parenthesis.
+6. No spaces for unary operators, `->` or `.`.
+7. No space before `:` but one after it, except in the ternary operator: one on both sides.
+8. Add spaces around all other operators.
+9. Braces, when used, always have their own lines and are at same indentation level as "parent" scope.
+10. If lines are broken, a list of elements enclosed with parentheses (of any kind) and separated by a separator (of any kind) are formatted such that there is exactly one element per line, followed by the separator, the opening parenthesis is on the first line, followed by a line break and the closing parenthesis is on a line of its own unindented). See example below.
+
+Yes:
+```cpp
 if (a == b[i])
     printf("Hello\n");	// NOTE spaces used instead of tab here for clarity - first byte should be '\t'.
 foo->bar(
@@ -44,99 +33,92 @@ cout <<
     "text that talks about this and that and contains the words " <<
     "\"lorem\" and \"ipsum\"" <<
     endl;
+```
 
+No:
+```cpp
+if( a==b[ i ] ) { printf ("Hello\n"); }
+foo->bar(someLongVariableName,
+         anotherLongVariableName,
+         anotherLongVariableName,
+         anotherLongVariableName,
+         anotherLongVariableName);
+cout << "some very long string that contains completely irrelevant text that talks about this and that and contains the words \"lorem\" and \"ipsum\"" << endl;
+```
 
+## 1. Namespaces
 
-1. Namespaces;
+1. No `using namespace` declarations in header files.
+2. All symbols should be declared in a namespace except for final applications.
+3. Use anonymous namespaces for helpers whose scope is a cpp file only.
+4. Preprocessor symbols should be prefixed with the namespace in all-caps and an underscore.
 
-a. No "using namespace" declarations in header files.
-b. All symbols should be declared in a namespace except for final applications.
-c. Use anonymous namespaces for helpers whose scope is a cpp file only.
-d. Preprocessor symbols should be prefixed with the namespace in all-caps and an underscore.
+Yes:
+```cpp
+#include <cassert>
+std::tuple<float, float> meanAndSigma(std::vector<float> const& _v);
+```
 
-(WRONG)
+No:
+```cpp
 #include <cassert>
 using namespace std;
 tuple<float, float> meanAndSigma(vector<float> const& _v);
+```
 
-(CORRECT)
-#include <cassert>
-std::tuple<float, float> meanAndSigma(std::vector<float> const& _v);
-
-
-
-2. Preprocessor;
-
-a. File comment is always at top, and includes:
-- Copyright.
-- License (e.g. see COPYING).
-b. Never use #ifdef/#define/#endif file guards. Prefer #pragma once as first line below file comment.
-c. Prefer static const variable to value macros.
-d. Prefer inline constexpr functions to function macros.
-e. Split complex macro on multiple lines with '\'.
-
-
+## 2. Preprocessor
 
-3. Capitalization;
+1. File comment is always at top, and includes:
+   - Copyright
+   - License (e.g. see COPYING)
+2. Never use `#ifdef`/`#define`/`#endif` file guards. Prefer `#pragma` once as first line below file comment.
+3. Prefer static const variable to value macros.
+4. Prefer inline constexpr functions to function macros.
+5. Split complex macro on multiple lines with `\`.
 
-GOLDEN RULE: Preprocessor: ALL_CAPS; C++: camelCase.
+## 3. Capitalization
 
-a. Use camelCase for splitting words in names, except where obviously extending STL/boost functionality in which case follow those naming conventions.
-b. The following entities' first alpha is upper case:
-- Type names.
-- Template parameters.
-- Enum members.
-- static const variables that form an external API.
-c. All preprocessor symbols (macros, macro arguments) in full uppercase with underscore word separation.
+**GOLDEN RULE**: Preprocessor: `ALL_CAPS`; C++: `camelCase`.
 
+1. Use camelCase for splitting words in names, except where obviously extending STL/boost functionality in which case follow those naming conventions.
+2. The following entities' first alpha is upper case:
+   - Type names
+   - Template parameters
+   - Enum members
+   - static const variables that form an external API.
+3. All preprocessor symbols (macros, macro arguments) in full uppercase with underscore word separation.
 
 All other entities' first alpha is lower case.
 
+## 4. Variable prefixes
 
+1. Leading underscore "_" to parameter names:
+   - Exception: "o_parameterName" when it is used exclusively for output. See 6(f).
+   - Exception: "io_parameterName" when it is used for both input and output. See 6(f).
+2. Leading "g_" to global (non-const) variables.
+3. Leading "s_" to static (non-const, non-global) variables.
 
-4. Variable prefixes:
-
-a. Leading underscore "_" to parameter names.
-- Exception: "o_parameterName" when it is used exclusively for output. See 6(f).
-- Exception: "io_parameterName" when it is used for both input and output. See 6(f).
-b. Leading "g_" to global (non-const) variables.
-c. Leading "s_" to static (non-const, non-global) variables.
-
-
-
-5. Assertions:
-
-- use `solAssert` and `solUnimplementedAssert` generously to check assumptions
-  that span across different parts of the code base, for example before dereferencing
-  a pointer.
-
-
-6. Declarations:
-
-a. {Typename} + {qualifiers} + {name}.
-b. Only one per line.
-c. Associate */& with type, not variable (at ends with parser, but more readable, and safe if in conjunction with (b)).
-d. Favour declarations close to use; don't habitually declare at top of scope ala C.
-e. Pass non-trivial parameters as const reference, unless the data is to be copied into the function, then either pass by const reference or by value and use std::move.
-f. If a function returns multiple values, use std::tuple (std::pair acceptable) or better introduce a struct type. Do not use */& arguments.
-g. Use parameters of pointer type only if ``nullptr`` is a valid argument, use references otherwise. Often, ``boost::optional`` is better suited than a raw pointer.
-h. Never use a macro where adequate non-preprocessor C++ can be written.
-i. Only use ``auto`` if the type is very long and rather irrelevant.
-j. Do not pass bools: prefer enumerations instead.
-k. Prefer enum class to straight enum.
-l. Always initialize POD variables, even if their value is overwritten later.
+## 5. Assertions
 
+Use `solAssert` and `solUnimplementedAssert` generously to check assumptions that span across different parts of the code base, for example before dereferencing a pointer.
 
-(WRONG)
-const double d = 0;
-int i, j;
-char *s;
-float meanAndSigma(std::vector<float> _v, float* _sigma, bool _approximate);
-Derived* x(dynamic_cast<Derived*>(base));
-for (map<ComplexTypeOne, ComplexTypeTwo>::iterator i = l.begin(); i != l.end(); ++l) {}
+## 6. Declarations
 
+1. {Typename} + {qualifiers} + {name}.
+2. Only one per line.
+3. Associate */& with type, not variable (at ends with parser, but more readable, and safe if in conjunction with (b)).
+4. Favour declarations close to use; don't habitually declare at top of scope ala C.
+5. Pass non-trivial parameters as const reference, unless the data is to be copied into the function, then either pass by const reference or by value and use std::move.
+6. If a function returns multiple values, use std::tuple (std::pair acceptable) or better introduce a struct type. Do not use */& arguments.
+7. Use parameters of pointer type only if ``nullptr`` is a valid argument, use references otherwise. Often, ``boost::optional`` is better suited than a raw pointer.
+8. Never use a macro where adequate non-preprocessor C++ can be written.
+9. Only use ``auto`` if the type is very long and rather irrelevant.
+10. Do not pass bools: prefer enumerations instead.
+11. Prefer enum class to straight enum.
+12. Always initialize POD variables, even if their value is overwritten later.
 
-(CORRECT)
+Yes:
+```cpp
 enum class Accuracy
 {
 	Approximate,
@@ -154,78 +136,78 @@ char* s;
 MeanAndSigma ms meanAndSigma(std::vector<float> const& _v, Accuracy _a);
 Derived* x = dynamic_cast<Derived*>(base);
 for (auto i = x->begin(); i != x->end(); ++i) {}
+```
 
+No:
+```cp
+const double d = 0;
+int i, j;
+char *s;
+float meanAndSigma(std::vector<float> _v, float* _sigma, bool _approximate);
+Derived* x(dynamic_cast<Derived*>(base));
+for (map<ComplexTypeOne, ComplexTypeTwo>::iterator i = l.begin(); i != l.end(); ++l) {}
+```
 
-7. Structs & classes
-
-a. Structs to be used when all members public and no virtual functions.
-- In this case, members should be named naturally and not prefixed with 'm_'
-b. Classes to be used in all other circumstances.
-
-
-
-8. Members:
-
-a. One member per line only.
-b. Private, non-static, non-const fields prefixed with m_.
-c. Avoid public fields, except in structs.
-d. Use override, final and const as much as possible.
-e. No implementations with the class declaration, except:
-- template or force-inline method (though prefer implementation at bottom of header file).
-- one-line implementation (in which case include it in same line as declaration).
-f. For a property 'foo'
-- Member: m_foo;
-- Getter: foo() [ also: for booleans, isFoo() ];
-- Setter: setFoo();
-
-
-
-9. Naming
-
-a. Avoid unpronouncable names
-b. Names should be shortened only if they are extremely common, but shortening should be generally avoided
-c. Avoid prefixes of initials (e.g. do not use IMyInterface, CMyImplementation)
-c. Find short, memorable & (at least semi-) descriptive names for commonly used classes or name-fragments.
-- A dictionary and thesaurus are your friends.
-- Spell correctly.
-- Think carefully about the class's purpose.
-- Imagine it as an isolated component to try to decontextualise it when considering its name.
-- Don't be trapped into naming it (purely) in terms of its implementation.
-
-
-
-10. Type-definitions
-
-a. Prefer 'using' to 'typedef'. e.g. using ints = std::vector<int>; rather than typedef std::vector<int> ints;
-b. Generally avoid shortening a standard form that already includes all important information:
-- e.g. stick to shared_ptr<X> rather than shortening to ptr<X>.
-c. Where there are exceptions to this (due to excessive use and clear meaning), note the change prominently and use it consistently.
-- e.g. using Guard = std::lock_guard<std::mutex>; ///< Guard is used throughout the codebase since it is clear in meaning and used commonly. 
-d. In general expressions should be roughly as important/semantically meaningful as the space they occupy.
-e. Avoid introducing aliases for types unless they are very complicated. Consider the number of items a brain can keep track of at the same time.
-
-
-
-11. Commenting
-
-a. Comments should be doxygen-compilable, using @notation rather than \notation.
-b. Document the interface, not the implementation.
-- Documentation should be able to remain completely unchanged, even if the method is reimplemented.
-- Comment in terms of the method properties and intended alteration to class state (or what aspects of the state it reports).
-- Be careful to scrutinise documentation that extends only to intended purpose and usage.
-- Reject documentation that is simply an English transaction of the implementation.
-c. Avoid in-code comments. Instead, try to extract blocks of functionality into functions. This often already eliminates the need for an in-code comment.
-
-
-12. Include Headers
-
-Includes should go in increasing order of generality (libsolidity -> libevmasm -> libdevcore -> boost -> STL).
-The corresponding .h file should be the first include in the respective .cpp file.
-Insert empty lines between blocks of include files.
+## 7. Structs & classes
+
+1. Structs to be used when all members public and no virtual functions:
+   - In this case, members should be named naturally and not prefixed with `m_`.
+2. Classes to be used in all other circumstances.
+
+## 8. Members
+
+1. One member per line only.
+2. Private, non-static, non-const fields prefixed with `m_`.
+3. Avoid public fields, except in structs.
+4. Use override, final and const as much as possible.
+5. No implementations with the class declaration, except:
+   - template or force-inline method (though prefer implementation at bottom of header file).
+   - one-line implementation (in which case include it in same line as declaration).
+6. For a property `foo`
+   - Member: `m_foo`
+   - Getter: `foo()` [ also: for booleans, `isFoo()` ]
+   - Setter: `setFoo()`
+
+## 9. Naming
+
+1. Avoid unpronouncable names.
+2. Names should be shortened only if they are extremely common, but shortening should be generally avoided
+3. Avoid prefixes of initials (e.g. do not use `IMyInterface`, `CMyImplementation`)
+4. Find short, memorable & (at least semi-) descriptive names for commonly used classes or name-fragments:
+   - A dictionary and thesaurus are your friends;
+   - Spell correctly;
+   - Think carefully about the class's purpose;
+   - Imagine it as an isolated component to try to decontextualise it when considering its name;
+   - Don't be trapped into naming it (purely) in terms of its implementation.
+
+## 10. Type definitions
+
+1. Prefer `using` to `typedef`. e.g. `using ints = std::vector<int>;` rather than typedef `std::vector<int> ints;`
+2. Generally avoid shortening a standard form that already includes all important information:
+   - e.g. stick to `shared_ptr<X>` rather than shortening to `ptr<X>`.
+3. Where there are exceptions to this (due to excessive use and clear meaning), note the change prominently and use it consistently:
+   - e.g. `using Guard = std::lock_guard<std::mutex>;` ///< Guard is used throughout the codebase since it is clear in meaning and used commonly. 
+4. In general expressions should be roughly as important/semantically meaningful as the space they occupy.
+5. Avoid introducing aliases for types unless they are very complicated. Consider the number of items a brain can keep track of at the same time.
+
+## 11. Commenting
+
+1. Comments should be doxygen-compilable, using @notation rather than \notation.
+2. Document the interface, not the implementation:
+   - Documentation should be able to remain completely unchanged, even if the method is reimplemented;
+   - Comment in terms of the method properties and intended alteration to class state (or what aspects of the state it reports);
+   - Be careful to scrutinise documentation that extends only to intended purpose and usage;
+   - Reject documentation that is simply an English transaction of the implementation.
+3. Avoid in-code comments. Instead, try to extract blocks of functionality into functions. This often already eliminates the need for an in-code comment.
+
+## 12. Include Headers
+
+1. Includes should go in increasing order of generality (`libsolidity` -> `libevmasm` -> `libdevcore` -> `boost` -> `STL`).
+2. The corresponding `.h` file should be the first include in the respective `.cpp` file.
+3. Insert empty lines between blocks of include files.
 
 Example:
-
-```
+```cpp
 #include <libsolidity/codegen/ExpressionCompiler.h>
 
 #include <libsolidity/ast/AST.h>
@@ -245,18 +227,17 @@ Example:
 #include <numeric>
 ```
 
-See http://stackoverflow.com/questions/614302/c-header-order/614333#614333 for the reason: this makes it easier to find missing includes in header files.
-
+See [this issue](http://stackoverflow.com/questions/614302/c-header-order/614333#614333 "C header order") for the reason: this makes it easier to find missing includes in header files.
 
-13. Recommended reading
+## 13. Recommended reading
 
-Herb Sutter and Bjarne Stroustrup
-- "C++ Core Guidelines" (https://github.com/isocpp/CppCoreGuidelines/blob/master/CppCoreGuidelines.md)
+- Herb Sutter and Bjarne Stroustrup:
+  - [C++ Core Guidelines](https://github.com/isocpp/CppCoreGuidelines/blob/master/CppCoreGuidelines.md)
 
-Herb Sutter and Andrei Alexandrescu
-- "C++ Coding Standards: 101 Rules, Guidelines, and Best Practices"
+- Herb Sutter and Andrei Alexandrescu:
+  - "C++ Coding Standards: 101 Rules, Guidelines, and Best Practices"
 
-Scott Meyers
-- "Effective C++: 55 Specific Ways to Improve Your Programs and Designs (3rd Edition)"
-- "More Effective C++: 35 New Ways to Improve Your Programs and Designs"
-- "Effective Modern C++: 42 Specific Ways to Improve Your Use of C++11 and C++14"
+- Scott Meyers:
+  - "Effective C++: 55 Specific Ways to Improve Your Programs and Designs (3rd Edition)"
+  - "More Effective C++: 35 New Ways to Improve Your Programs and Designs"
+  - "Effective Modern C++: 42 Specific Ways to Improve Your Use of C++11 and C++14"