Difference between revisions of "VTK Coding Standards"

From KitwarePublic
Jump to navigationJump to search
Line 1: Line 1:
==Coding Standards==
 
 
 
We only have a few coding standards but they have proved very useful.
 
We only have a few coding standards but they have proved very useful.
  
Line 31: Line 29:
 
     }
 
     }
  
* 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.
+
* The header file of the class should include only the superclasses header file. If you do not, the header test run as part of the VTK dashboard will report an error. If any other includes are absolutely necessary, include comment at each one describing why it should be included:
 +
 
 +
#include "vtkKWWindow.h"
 +
#include "vtkClientServerID.h" // Needed for InteractorID
 +
#include "vtkPVConfig.h" // Needed for PARAVIEW_USE_LOOKMARKS
 +
 
 +
* Avoid using vtkSetObjectMacro since it will require including the header file of another class. Use the vtkCxxSetObjectMacro instead. For example:
 +
 
 +
  // Class declaration:
 +
  // Description:
 +
  // Set/Get the array used to store the visibility flags.
 +
  void SetVisibilityById(vtkUnsignedCharArray* vis);
 +
 
 +
  // Cxx file
 +
  vtkCxxSetObjectMacro(vtkStructuredVisibilityConstraint,
 +
                      VisibilityById,
 +
                      vtkUnsignedCharArray);
 +
 
 +
* All subclasses of vtkObject should inclued a PrintSelf() method that prints all publicly accessible ivars. For example:
 +
 
 +
void vtkObject::PrintSelf(ostream& os, vtkIndent indent)
 +
{
 +
  os << indent << "Debug: " << (this->Debug ? "On\n" : "Off\n");
 +
  os << indent << "Modified Time: " << this->GetMTime() << "\n";
 +
  this->Superclass::PrintSelf(os, indent);
 +
  os << indent << "Registered Events: ";
 +
  if ( this->SubjectHelper )
 +
    {
 +
    os << endl;
 +
    this->SubjectHelper->PrintSelf(os,indent.GetNextIndent());
 +
    }
 +
  else
 +
    {
 +
    os << "(none)\n";
 +
    }
 +
  }
 +
 
 +
* All subclasses of vtkObject should include a type macro in their class declaration. For example:
 +
 
 +
class VTK_COMMON_EXPORT vtkBox : public vtkImplicitFunction
 +
{
 +
public:
 +
  vtkTypeRevisionMacro(vtkBox,vtkImplicitFunction);
 +
  void PrintSelf(ostream& os, vtkIndent indent);
 +
...
 +
}
 +
 
 +
* If using STL, follow the guidelines specified in the [[VTK FAQ#Can I use STL with VTK?|VTK FAQ]].
 +
 
 +
* When using anything declared in iostream, do not use std:: or vtkstd::. Examples include cerr, cout, ios... Do not include the iostream header. It is already included.

Revision as of 10:12, 26 October 2004

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 do not, the header test run as part of the VTK dashboard will report an error. If any other includes are absolutely necessary, include comment at each one describing why it should be included:
#include "vtkKWWindow.h"
#include "vtkClientServerID.h" // Needed for InteractorID
#include "vtkPVConfig.h" // Needed for PARAVIEW_USE_LOOKMARKS
  • Avoid using vtkSetObjectMacro since it will require including the header file of another class. Use the vtkCxxSetObjectMacro instead. For example:
 // Class declaration: 
 // Description:
 // Set/Get the array used to store the visibility flags.
 void SetVisibilityById(vtkUnsignedCharArray* vis);
 // Cxx file
 vtkCxxSetObjectMacro(vtkStructuredVisibilityConstraint,
                      VisibilityById,
                      vtkUnsignedCharArray);
  • All subclasses of vtkObject should inclued a PrintSelf() method that prints all publicly accessible ivars. For example:
void vtkObject::PrintSelf(ostream& os, vtkIndent indent)
{
  os << indent << "Debug: " << (this->Debug ? "On\n" : "Off\n");
  os << indent << "Modified Time: " << this->GetMTime() << "\n";
  this->Superclass::PrintSelf(os, indent);
  os << indent << "Registered Events: ";
  if ( this->SubjectHelper )
    {
    os << endl;
    this->SubjectHelper->PrintSelf(os,indent.GetNextIndent());
    }
  else
    {
    os << "(none)\n";
    }
 }
  • All subclasses of vtkObject should include a type macro in their class declaration. For example:
class VTK_COMMON_EXPORT vtkBox : public vtkImplicitFunction
{
public:
  vtkTypeRevisionMacro(vtkBox,vtkImplicitFunction);
  void PrintSelf(ostream& os, vtkIndent indent);
...
}
  • If using STL, follow the guidelines specified in the VTK FAQ.
  • When using anything declared in iostream, do not use std:: or vtkstd::. Examples include cerr, cout, ios... Do not include the iostream header. It is already included.