CIBC:Documentation:SCIRun:DevManual:CodingStandards

From SCIRun Documentation Wiki
Jump to navigation Jump to search

Coding standards

Required Coding Standards

  • All code and comments are to be written in English.
  • All files must include appropriate license information.
  • Use the C++ mode in GNU Emacs and sci-c++-style.el to format code.
  • Include files in C++ always have the file name extension .h.
  • Implementation files in C++ always have the file name extension .cc.
  • Every include file must contain a 'guard' that prevents multiple inclusions of the file, for example:
#ifndef CORE_GEOMETRY_BBOX_H 
#define CORE_GEOMETRY_BBOX_H 1

// Code...

#endif
  • The name of the guard should be of the following form: DIR_DIR_FILENAME_H
  • Use forward declarations wherever possible as opposed to including full definitions for classes, functions, and data:
// Class
class PointToMe;

// Function
void my_function(PointToMe &p, PointToMe *ptm);

// Data
PointToMe *m;
  • The names of variables and functions will begin with a lowercase letter and include underscore word separators. Names of constants should be in all CAPITALS, with underscore word separation:
static int CONSTANT_INT_FIVE = 5;
void my_function_name();
int my_local_variable_name = 0;
  • The names of class member variables are to end with an underscore, '_':
class SomeObject {
  int count_;
};


  • The names of abstract data types (that is, classes), and structs are to begin with an uppercase letter, and each new word in the name should also be capitalized.
class MyNewClassName {
  // ...
};
  • All member functions which do not change an object's state should be declared const
  • Constants are to be defined using const or enum. Never use #define to create constants.
  • A class which uses new to allocate instances managed by the class must define a copy constructor and an assignment operator.
  • Classes should never assume that the input is perfect and a sensible number of safety checks should be in place to detect faulty inputs.
  • Use exception handling to trap errors (although exceptions should only be used for trapping truly exceptional events).
  • Our exception model includes two levels of exceptions. The top level of exceptions are defined in Core/Exceptions/Exceptions.h and are thrown when a class specific exception is not appropriate. The bottom level of exceptions are class specific, defined in the class that throws them, and are subclassed off of the top level exceptions. These class specific exceptions are exceptions that can be caught and handled from the calling function (1 level above the class.) However, if the calling function chooses not to (or cannot) handle the class specific exception, the exception will propagate to the next level at which point it can be trapped and handled in the form of a top level exception. An example of a class specific exception would be a StackUnderFlowException for a stack class.
  • Comments should support generated documentation format. Comments in declarations should be of the form:
//! comment ..

or 

/*! comment */

These comments will then be visible in our online documentation. Comments in the definition part of your code need not have the !, as all the code is visible online including comments. Create comments that help the reader navigate your code. Comments should help the reader find the area of code he/she is looking for quickly.

  • Do not use identifiers which begin with an underscores ('_').
  • Do not use #define to obtain more efficient code; use inline functions instead.
  • Avoid the use of numeric values in code; use symbolic values instead. This applies to numeric values that are repeated within the code but represent the same value. Eg: MAX_ARRAY_SIZE = 1024.
  • Do not compare a pointer to NULL or assign NULL to a pointer; use 0 instead.
  • Avoid explicit type conversions (casts). However when a cast is needed, an explicit cast is preferred over having the compiler decide which kind of cast to do.
  • Never convert a constant to a non-constant. Use mutable if necessary. However, be aware of the thread safety problems this causes.
  • Never use goto.
  • Do not use malloc, realloc, or free. Use new and delete instead.

Recommended coding standards

  • Never use more than 80 columns per line.
  • An include file for a class should have a file name of the form class name.h. Use uppercase and lowercase letters in the same way as in the source code.
  • Never include /usr/include/*.h, for example iostream.h in any header file. This causes a huge amount of code to be recursively included and needlessly compiled. Use forward declarations to avoid this.
  • Group local includes together, then group system includes together.
  • Avoid global data if possible.
  • Optimize code only if you know that you have a performance problem. Think twice before you begin.
  • Always force your compiler to compile with the maximum warning setting, and before you check in code, fix all warnings.
  • Place machine-dependent code in a special file so that it may be easily located when porting code from one machine to another.
  • Encapsulate global variables and constants, enumerated types, and typedefs in a class.
  • Functions in general should not be more than 30 lines long (excluding documentation and indentation). If you find this situation, break the function into several smaller functions.
  • If a function stores a pointer to an object which is accessed via an argument, let the argument have the type pointer. Use reference arguments in other cases.
  • When overloading functions, all variations should have the same semantics (be used for the same purpose).
  • Do not assume that you know how the invocation mechanism for a function is implemented.
  • Do not assume that an object is initialized in any special order in constructors.
  • Use a typedef to simplify program syntax when declaring function pointers, or templated types.
  • When two operators are opposites (such as == and !=), it is appropriate to define both.
  • Use constant references (const &) instead of call-by-value, unless using a predefined data type or a pointer.
  • Minimize the number of temporary objects that are created as return values from functions or as arguments to functions.
  • Do not write code which is dependent on the lifetime of a temporary object.
  • Use parentheses to clarify the order of evaluation for operators in expressions.
  • Avoid using shift operations instead of arithmetic operations.
  • Use std::cout instead of printf.
  • Do not assume that longs, floats, doubles or long doubles may begin at arbitrary addresses.
  • Always use plain char if 8-bit ASCII is used. Otherwise, use signed char or unsigned char.
  • Do not assume that a char is signed or unsigned.
  • Do not depend on underflow or overflow functioning in any special way.
  • Avoid the use of using namespace std; (or other namespaces) in include files as they can spill into other files with unintended consequences.
  • Try to use smart pointers (Handles) to automatically deallocate memory when an object is not needed anymore.
  • When a function is pure, i.e. it does not modify any of the class members, annotate it as such so it can be used safely in multi threaded code.
  • When variables are being shared between threads always use a mutex for access control.
  • Use the string class and not C-strings where possible.

Go back to Documentation:SCIRun:DevManual

Retrieved from "http://scirundocwiki.sci.utah.edu/SCIRunDocs/index.php?title=CIBC:Documentation:SCIRun:DevManual:CodingStandards&oldid=6686"