VTK Coding Standards

From KitwarePublic
Revision as of 09:25, 26 October 2004 by Berk (talk | contribs) (first pass)
(diff) ← Older revision | Latest revision (diff) | Newer revision → (diff)
Jump to navigationJump to search

Coding Standards

We only have a few coding standards but they have proved very useful.

   * We only put one public class per file. Some classes have helper classes that they use, but these are not accessable to the user.
   * Every class, macro, etc starts with either vtk or VTK, this avoids name clashes with other libraries. Classes should all start with vtk and macros or constants can start with either.
   * Class names and file names are the same. This makes it easier to find the correct file for a specific class.
   * We only use alphanumeric characters in names, [a-zA-z0-9]. So names like Extract_Surface are not welcome. We use capitalization to indicate words within a name. For example ExtractVectorTopology could be an instance variable. If it were a class it would be called vtkExtractVectorTopology. We capitalize the first letter of a name (excluing any preceding vtk). For local variables almost anything goes. Ideally we would suggest using same same convention as instance variables except start their names with a lower case letter. e.g. extractVectorSurface.
   * We try to always spell out a name and not use abbreviations. This leads to longer names but it makes using the software easier because you know that the SetRasterFontRange method will always be called that, not SetRFRange or SetRFontRange or SetRFR. When the name includes a natural abbreviation such as OpenGL, we keep the abreviation and capitalize the appreviated letters.
   * We try to keep all instance variables protected. The user and application developer should access instance variables through Set/Get methods. To aid in this there are a number of macros defined in vtkSetGet.h that can be used. They expand into inline functions that Set/Get the instance variable and invoke a Modified() method if the value has changed.
   * Use "this" inside of methods even though C++ doesn't require you to. This really seems to make the code more readable because it disambiguates between instance variables and local or global variables. It also disambiguates between member functions and other functions.
   * Make sure your code compiles without any warnings with -Wall and -O2.
   * The indentation style can be characterized as the "indented brace" style. Indentations are two spaces, and the curly brace (scope delimiter) is placed on the following line and indented along with the code (i.e., the curly brace lines up with the code). Example:


 if (this->Locator == locator)
   {
   return;
   }
 for (i = 0; i < this->Source->GetNumberOfPoints(); i++)
   {
   p1 = this->Source->GetPoint(i);
   [...]
   }
   * The header file of the class should include only the superclasses header file. If you need any other includes, include comment at each one describing why it should be included.