CodingStyle.txt

Coding Style Rules
Cory Quammen <cquammen@cs.unc.edu>
Last update: March 8, 2013

----------------
C/C++ Code style
----------------

Consistent coding style within a source code project is important for
readability and a clean look to the code.

Code should adhere to this handful of formatting rules:

- Header source code files should have the extension .h

- C++ source code files should have the extention .cxx

- C Source code files should have the extention .c

- Use spaces, not tabs

- Nested code blocks should be indented by 2 spaces

- Function and method names should follow upper CAML case convention,
  e.g., ComputeValue(), NextSample(). Avoid using underscores to
  separate words (they slow down typing).

- Favor complete English words instead of abbreviations when naming
  variables and functions.

    Bad:    pn
    Better: paramName
    Best:   parameterName

- Class member variables should have the "m_" prefix, e.g. m_Value, m_Distance.

- When referring to a member variable, use "m_Var" rather than "this->m_Var".

- When referring to a method in the same class, use "this->Method()"
  rather than just "Method()".

- Include the header files that defined the types you used, but include
  no more headers than that.

- For C++, classes and functions for MADAI software should exist
  within the "madai" namespace

- Avoid "using namespace std;" like you would avoid the
  plague. Slightly better alternative: "using std::string;" Preferred:
  used std::string throughout your code. The problem with refering to
  "string" in source code is that we may someday include a library
  that defines it's own string type. This will confuse the compiler
  and cause all kinds of headaches. To be safe, always use
  "std::string".

- Listen to the compiler warnings.  Make sure that the GCC's
  "-Wall -Wextra -pedantic -Wno-long-long" settings don't trigger
  warnings.  Be sure to check in both debug and release mode.

-----------------------
Shell Script Code style
-----------------------

- Shell scripts should be used only for the convenience of
  Unix/MacOS10.x/Linux/POSIX users.  Shell scripts should adhere to
  the POSIX portability standards defined here:
    http://pubs.opengroup.org/onlinepubs/009695399/utilities/sh.html
    http://pubs.opengroup.org/onlinepubs/009695399/utilities/xcu_chap02.html

-----------------
Python Code style
-----------------

- Avoid language features introduced since version 2.4 for maximum
  backwards compatibility, unless absolutly necessary.

- Use tabs for indentation, not spaces.  Tell your text editor to
  interpret a tab as 4 spaces.

- If your program has functions that may be useful in another context,
  use the "if __name__=='__main__':" trick to allow a program to be
  used as a module.

- For everything else, adhere to PEP 8.