Programming Guidelines

1. Definitions

2. Naming

2.a. File names and content

• All files must include a standard header with a copyright.
• Try to have only one class per file and the file basename must match the class name. The name starts with the package prefix in lower case letters. Then we used lower case letters expect to indicate the beginning of a word. No separator is to be used for the class name (such as underscore _ or dash -). Example: cisIntVec3.h
• Suffices are .h for headers and .cpp for source files.
• All include files must have "include's guards" to avoid multiple definitions. They will match the package name and class name. Therefore, right after the copyright header, we must have something like:

  #ifndef _cisMyClass_h
  #define _cisMyClass_h
  

• Don't forget the #endif at the end of each include file.
• Since the include file has only definitions and no code, inline methods implementation have to be placed somewhere else. We recommend to create a cisMyClass-inl.h file.
• The inline file (cisMyClass-inl.h) must be included only by the corresponding header file (cisMyClass.h). To prevent any other inclusion, we recommend to add at the end of the declaration file (cisMyClass.h):

  #define _cisMyClass_inl_h
  #include <cisMyClass-inl.h>
  #undef _cisMyClass_inl_h
  

  The code of inline methods itself is in cisMyClass-inl.h and the file should have, right after the standard header:

  #ifndef _cisMyClass_inl_h
  #error "include of cisMyClass-inl.h is not allowed, include cisMyClass.h instead"
  #endif
  #undef _cisMyClass_inl_h
  

• Similar code is used for templates. Code has to be in file cisMyClass-tpl.h and the guard name is _cisMyClass_tpl_h

2.b. Classes, Methods, Data Members, Arguments, Variables and Macros

• Class: Class names start with the package prefix in lower case letters. Then we used lower case letters expect to indicate the beginning of a word. Name should be long enough to be explicit and avoid possible confusions. Example: cisMyTetrahedron and not MyTet.
• Method and Data member: Method and data member names (public, protected and private) have the first letter of each word capitalized and no separator is to be used (no underscore or dash). Names should be long enough to be explicit and avoid possible confusion. Example: SignedVolume and not SigVol.
• Arguments and variables: Arguments of function and methods as well as local variables should start with a lower case letter. If the method name is composed of two or more words, each new word starts with an upper case letter and no separator is to be used (no underscore or dash). Name should be long enough to be explicit and avoid possible confusions. Example: signedVolume.
• Macros: Macros have the package name as prefix in lower case letters and everything else is upper case. If the name is composed of two or more words, an underscore might be added to increase readability. Example: cisSWAP_ARRAYS.
• Constants: Constants created with #define or enumerations should be all uppercase with underscore for separation between words. Again, we use the package name in lower case as prefix. Example: mrcMY_CONSTANT.

• If it starts with an upper case letter, it is class related:
  • If it's in a declaration, it's a class name: cisTetrahedron t
  • It there are parentheses immediately after and we don't have the package prefix, it's a method: m.Tetrahedron()
  • Otherwise, it's a data member: m.Tetrahedron
• If it starts with a lower case, it has been declared locally and declaration should be on the same page: tetrahedron
• If it is all uppercase:
  • If there are parentheses immediately after, it's a macro: cisMAX(a, b)
  • If not, it's a defined constant or an enumeration type: cisRED

3. Formatting

3.a. Instructions

• To increase the readability and ease the debugging, use only one instruction per line. Example:

  int firstIndex;
  int* secondIndex;
  

  and not:

  int firstIndex, *secondIndex;
  

• For pointers and references, try to place the * or the * with the type, not with the variable name. Examples: int* index not int *index and cisMyClass& object not cisMyClass &object.
• Still to increase readability, avoid the syntax condition?statement1:statement2
• Use a space between operators, it is sometime necessary and it always helps. Example: i += *j.
• Always use a space after a comma (,) or a semi colon (;). Example: for (i = 0; i > 10; i++) but not for(i=0;i>10;i++).
• Use a single space between for, while, switch or if and the following parenthesis..
• If a method prototype is too long (i.e. approx 80 characters), arguments should be on different lines. Example:

  cisMyClassReturned
  cisMyVeryLongClassName::AnEvenLongerMethodName(const cisOtherClass& object1,
                                                 const cisAnOtherVeryLongClassName& object2)
  const
  

• In a method or function declaration declaration, explicitely specify void if there is no parameter. Example: int GetX(void) not int GetX()

3.b. Blocks of instructions

• Opening or closing curly brackets should be on separate lines and aligned with the beginning of the statment they are related to (at least for the closing one). Example:

  if (myFlag == true)
  {
      return false;
  }

  can also be written as

  if (myFlag == true) {
      return false;
  }

• For methods and functions, declaration keywords and return type should be on separate lines. Example:

  int
  cisGetIndexPointer(void)
  const
  {
      return cisGlobalExternObject->IndexPointer;
  }
  

4. Portability

• If you have some code which depends on the OS or the compiler, use well identified macros.
  For the compilers, the macros are:
  • Gnu compilers: __GNUC__
  from "man cpp"
  • Irix CC: !__GNUC__ tested with CC
  • Sun CC: __SUNPRO_CC to be tested
  • Visual C++: _MSC_VER (to be tested)
  For the operating system:
  • Unix: unix tested for gcc/linux, gcc/irix, gcc/solaris with "gnu cpp -dM"
  • Linux: linux tested for gcc with "cpp -dM"
  • Irix: mips or sgi (tested for gcc and CC)
  • Solaris: sparc or sun (tested for gcc)
  • Windows NT: WIN32 or _WIN32
• Avoid the declaration in the for statements since compilers have different ways to interpret them. Therefore, statement like for (int i; i < 10; i++) MUST be avoided.
• All modern compilers have a internal boolean type, therefore one should use bool, true and false.
• Respect the case in include file names, some operating systems (Windows family) will accept includes like #include <MaTh.h> but others won't (Solaris, Linux, Irix, etc.).
• Some compilers (gcc) send a warning if there is no extra line (newline character) after the last #endif of an include file (.h). Please add a blank line.

5. Other recommendations

• Try to not declare all data members as public and use protected for classes with inheritance.
• The short version of if/then/else, condition?statement1:statement2 should not be used for at least two reasons: readability and debugging. It is a clear example of multiple instructions on a single line.
.
• Use of the assert macro is encouraged but the condition must not have any "side effect" otherwise the released version will not act like the debug version.
• Don't use goto.
• Don't use a semi colon (;) after a curly bracket (}) except at the end of a class declaration.
• With return, don't use unnecessary parenthesis. It's a keyword, not a function.
• For macros, don't forget to protect with your variables with parenthesis in the body of your macro code.

6. Operating System and Compiler

6.1. Windows DLL

• cisEXPORT: For a variable, must be used in header file with syntax: extern cisEXPORT typename varname. The source file is not modified.
• cisEXPORT: For a function, must be used in header file with syntax: cisEXPORT returntype functionname(). The source file is not modified.
• cisEXPORT: For a class, must be used in header file with syntax: class cisEXPORT classname(). The source file is not modified.

6.2. Irix

• Silicon Graphics compilers can produce different binary formats, COFF (old, Irix 4.0.x), an old ELF (Irix 5.x, sometime refered as o32) and new ELF - both in 32 and 64 bits (n32 and 64). You can not mix these formats when linking! It is a common problem if you want to link with existing libraries.
• To determine which format you have, file an object file (either .o, .a or .so) and do file myFile.o. The result is human readable.
• To compile in 32 or 64 bits:
  • For Irix CC, you can use the environment variable SGI_ABI set either to -32 or -64. An other solution is to use the option -32 or -64 for both compile and link.
  • For gcc, you have to use the option -mabi=64 (default is 32 bits).