Style and Coding Guide

Table of Contents

• Code and Documentation Basics
• Documentation

Code and Documentation Basics

To keep coding consistent, legible and easy-to-read, please use the following style guide.

1. namespaces are lower case. Namespaces are technically snake_case, but should ideally only be one word (no underscores if at all possible). Be pithy and succinct with namespaces. Examples: madara, madara::knowledge
2. Classes are UppercaseFollowedByLowercaseForEachWord. Examples: KnowledgeBaseImpl
3. functions and variables are snake_case. Examples: save_checkpoint, save_context, my_var, etc. Private or protected class member variables have a trailing underscore (_). Examples: my_var_, private_var_, etc.
4. MACROS and ENUMS are UPPER_SNAKE_CASE. There are a few examples of lower_snake_case in the repository, but try to keep to UPPER_SNAKE_CASE for all future code and features. Examples: LOG_ALWAYS, LOG_MAJOR
5. Filenames are UppercaseFollowedByLowercaseForEachWord. Filenames always reflect the contents of the file. Class implementations should be separated into their own file names wherever possible. Examples: KnowledgeBaseImpl.h, KnowledgeBaseImpl.cpp.
6. Indentation is always 2 spaces, no tabs. 2 spaces aids in legibility of indentation in all editors and forms.
7. Braces should be Allman Style, where each brace { and closing brace } are on their own lines. K&R, where opening braces are on the same lines as other expressions, such as functions, should be avoided due to the difficulty in sometimes locating the opening braces, especially in if/else if/else control flows. Whenever possible, use braces on all if/else if/else control flows. This prevents accidents such as what happened with recent OpenSSL root exploits. So, please use braces judiciously and use the Allman style.
8. Columns are 80 characters or less. We enforce this to keep code legible for terminal viewing, but it also helps with viewing code in Github and other sites that create left-to-right scrolling for viewing files.
9. Documentation is with Doxygen. We use Javadoc style for tagging, such as @param, @return, etc. We'll discuss more about Documentation in a later section.

Documentation

1. Header files should be documented with @file, @author and a brief description for the file. This aids in finding useful information and implementations.
2. Classes should be documented in the header file with an @class and a @brief just above the class.
3. Members should be documented with comments with either a triple slash /// or a multi-line comment /** member docs **/
4. Functions should be documented with active descriptions about what the function does. Functions should always use multi-line comments /** Describes the function actions **/ and should have all parameters documented with @param and if there is a return value, it has to be documented with @return.
5. Internal Documentation

• All variable names should be descriptive and in snake_case. The more descriptive the variable names, the easier to follow the code and logic of the implementation
• All if/else statements and while/for loops more than 4-5 lines long should have the opening and closing braces documented about what the section/control flow is doing. This is especially important for if/else if/else control flows to help the reader understand what previous control segments were.
• In general, legibility should be preferred over code succinctness. Please put comments on their own lines and not in the same line as code. The latter is very easy to miss.