Coding style¶

C++¶

We have a rather complex set of requirements that are attached to this page (G4MICE-StyleGuide.pdf or G4MICE-StyleGuide.odt). These style requirements are checked automatically by the MAUS test suite using the script in tests/style/test_cpp_style.py The style checks are rather strict. You can explicitly set up to ignore errors on a particular line of a particular file by adding the text of the line to cpplint_exceptions.py as long as you have a convincing reason. If you want to just have a look at the cpplint output from a particular file, you can do

python ${MAUS_ROOT_DIR}/third_party/install/lib/cpplint.py <filename1> <filename2>

List of things to check that are not checked by cpplint:

• Code should be in namespace MAUS
• All of the formatting like where to put underscores etc

Python¶

Python code should pass the pylint static code analysis tool. This tool is automatically run by the MAUS test suite. Exceptions can be added by posting a comment like

my_bad_code = "something" #pylint: disable=R0101

where R0101 in this example is the error type raised by pylint. In some rare cases, for example where data files are formatted in a pythonic style, it is acceptable to except an entire python file from the style checks. Ask the MAUS project lead if you think this is the case.

Code Comments¶

Comments are a vital part of making code readable. We use the doxygen program to automatically generate nicely formatted documentation for our code based on the comments in header files. Python comments are done using the native python docstrings while C++ comments are made at the top of each file and above each method. In general you should have one comment describing a class and one comment for each member function. Functions which do "the obvious thing" should have a docstring to indicate this.

C++ Comments¶

C++ comments sit in the header file and should look like this:

/** @class MyClass
 *  @author Joe Bloggs
 *  @brief One-line summary of what the class does
 *
 *  Full description of what the class does
 */
class MyClass {
 public:

  /** @brief One-line summary of what the method does
  *
  *  Full description of what the method does
  *
  *  @tparam <T> A description of the template parameter
  *  @param[in] Parameter1 A description of the parameter
  *  @param[out] Parameter2 A description of the parameter
  *
  *  @return A description of the returned object
  */
  template<typename T>
  T MyFunction(int Parameter1, int& Parameter2);

 private:
  int mMyMember /** A brief description */
};

Additional comments should also go in the source files to explain any details of how functions are implemented. Functions which take or return a pointer should declare in the comment who owns the memory.

Python Comments¶

Python comments are done using docstrings and should look like this:

def MyFunction(Parameter1, Parameter2):
    """ 
    @brief One-line summary of method functionality

    Full description of the method functionality

    @param Parameter1 int that does this
    @param Parameter2 int that does that

    @return Returns int that means something
   """ 
   <some code>

As python has weak typing, it is virtually essential that you specify what types are allowed for each parameter. Additional comments are welcome to explain any details of how functions are implemented. Note that python docstrings can be accessed and modified inline using the __doc__ parameter

Bash scripts¶

Avoid bash scripts and use python. If you really need a shell script:

• Any given line should not exceed 80 characters (including spaces) for historical reasons from what default terminal sizes are in linux, so within this program I don't exceed 70 since I don't like things cramming up against the side of windows.
• Any given line should not exceed more than 45-65 of characters (ignoring whitespace) for human cognition reasons (see link), so I've chosen 50 arbitrarily.

See Also¶

• Doxygen manual
• List of doxygen commands