Coding Guide

Does foo and bar. /// /// Does not do foo the usual way if baz is true. /// Add reference to implemented papers /// /// Typical usage: ///

Introduction

This guide collates best practices from a variety of sources, while some of these express a certain taste we want the items that are covered here to be consistent across iMSTK.

Coding style is not only limited to the actual formatting but also to things like the naming of functions or variables, or the use of certain c++ features or patterns. By being consistent in these we make development for iMSTK easier for ourselves and others as names and patterns are reused across the code base.

While the text of this guide is mostly culled from the OpenSurgSim coding guide the following resources were used to create and refine the style

• C++ Core Guidelines
• Google C++ Style guide
• High Integrity C++ Coding Standard

How to apply these standards

• When working with existing code, fix its shortcomings as necessary.
• When extending code created externally to the project (e.g. VTK, Eigen), try to remain consistent with the naming conventions of the external code.
• Be flexible and reasonable. If the best thing for code readability is to violate these guidelines, please do so but that is rarely the case.
• When in doubt, ask someone else for a second opinion.

Layout, white space and comments

First and foremost, be reasonable and pay attention to clarity. White space and comments are to aid in code readability, not detract from it.

Layout

• Use uncrustify to fix the formatting before you submit a merge request, the CodeFormatEnforcer target will correct all formatting issues.

Comments

• In general, the code should be made as self-documenting as possible by appropriate name choices and an explicit logical structure.
• All comments should be written in US English, be spelled correctly, and make grammatical sense.

• Use doxygen style comments.

  Example: ``` ///

  ///   fooBar(false, "quux", Res);
  /// 

  /// ///

  Note

  Take care not to create a division by zero /// ///

  Parameters

  	quux	kind of foo to do. ///
  [out]	result	filled with bar sequence on foo success. /// ///

  Exceptions

  if	a division by zero occurs /// ///

  Returns

  true on success. /// ///

  Warning

  missing feature bool fooBar(bool baz, StringRef quux, std::vector<int>& result);

  * Prefer using `//` for all embedded comments, including multi-line comments, using `/*`, `*/` prevents the use of that style comment around it.
  
      Example:

  // Comment spanning // more than one line.

  * Document responsibilities and background rather than what the code does, especially inline. The code should be readable and its details shouldn't need documentation. 
  
      Example : 

  /// ///