From 9b7a2b7a2da4654d8aa8abcc9459a45ae5ecf830 Mon Sep 17 00:00:00 2001 From: Gav Wood Date: Fri, 13 Feb 2015 16:51:09 +0100 Subject: [PATCH] Coding standard updates on documentation. --- CodingStandards.txt | 23 +++++++++++++++++++---- 1 file changed, 19 insertions(+), 4 deletions(-) diff --git a/CodingStandards.txt b/CodingStandards.txt index 76e1203a4..e1a1b3ba9 100644 --- a/CodingStandards.txt +++ b/CodingStandards.txt @@ -72,6 +72,8 @@ e. Split complex macro on multiple lines with '\'. 3. Capitalization; +GOLDEN RULE: Preprocessor: ALL_CAPS; C++: camelCase. + 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. @@ -80,6 +82,7 @@ b. The following entities' first alpha is upper case: - static const variables that form an external API. c. All preprocessor symbols (macros, macro argments) in full uppercase with underscore word separation. + All other entities' first alpha is lower case. @@ -137,6 +140,7 @@ for (auto i = x.begin(); i != x.end(); ++i) {} 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. @@ -146,7 +150,7 @@ b. Classes to be used in all other circumstances. 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 judiciously. +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). @@ -169,14 +173,18 @@ c. Avoid unpronouncable names; - If you need to shorten a name favour a pronouncable slice of the original to a scatterred set of consonants. - e.g. Manager shortens to Man rather than Mgr. d. Avoid prefixes of initials (e.g. DON'T use IMyInterface, CMyImplementation) -e. A dictionary and thesaurus are your friends. +e. Find short, memorable & (at least semi-) descriptive names for commonly used classes or name-fragments. +- A dictionary and thesaurus are your friends. - Spell correctly. -- Find short, memorable & (at least semi-) descriptive names for commonly used classes or name-fragments. +- 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; rather than typedef std::vector ints; +a. Prefer 'using' to 'typedef'. e.g. using ints = std::vector; rather than typedef std::vector ints; b. Generally avoid shortening a standard form that already includes all important information: - e.g. stick to shared_ptr rather than shortening to ptr. c. Where there are exceptions to this (due to excessive use and clear meaning), note the change prominently and use it consistently. @@ -184,9 +192,16 @@ c. Where there are exceptions to this (due to excessive use and clear meaning), d. In general expressions should be roughly as important/semantically meaningful as the space they occupy. + 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. + 12. Include Headers