Slicer:Style and Conventions

See Slicer3:Style for information on code contributions and expectations.

Coding Conventions

• Code that inherits from VTK classes should follow VTK coding conventions for naming, indentation, etc. See http://www.vtk.org/Wiki/VTK_Coding_Standards for details.
• This will simplify debugging of code that relies on the VTK object model, command observer structures, and other key VTK elements.
• Use STL where you can, but follow the VTK guidelines
• Configure your text editor to do VTK style indentation:
  • Emacs
  • Vi/Vim
  • Visual Studio

Naming

• Acronyms should be written in all CAPS.
  • For example: RASToSlice not RasToSlice
  • vtkMRML not vtkMrml
• Words should be spelled out and not abreviated
  • For example: GetWindow not GetWin
• Local variable should start with a lower case.
  • For example:

void vtkSlicerSliceLogic::SetForegroundLayer(vtkSlicerSliceLayerLogic *ForegroundLayer) // wrong!

should be

void vtkSlicerSliceLogic::SetForegroundLayer(vtkSlicerSliceLayerLogic *foregroundLayer)

• Member variable should start with a capital letter, and in implementation should be used in conjunction with 'this->' convention
  • For example

class Node {
  Object &Foo();
  Object Bla;
};
Object& Node::Foo()
{
  return this->Bla;
}

• Module GUI classes (those derived from vtkSlicerComponentGUI or vtkSlicerModuleGUI, which contain widgets, GUI building and mediator methods) should all have the prefix vtkSlicer and the suffix GUI.
  • For example: vtkSlicerVolumesGUI or vtkSlicerFiducialsGUI
• For now, widgets derived from vtkKW classes should end in Widget, Editor, or Viewer (this convention may change)
  • For example: vtkSlicerSliceViewerWidget or vtkSlicerWindowLevelThresholdEditor

Comments

• include extensive comments in the header files
• keep the comments up to date as the code changes
• use the keyword TODO to flag spots in the code that need to be revisited
• do not leave blocks of commented out code in the source file -- if needed insert links to prior svn versions as comments

Library Dependencies

• MRML classes should only depend on vtk and itk (not Slicer Logic or GUI)
• Logic classes depend on MRML to store state
• Logic classes should encapsulate vtk and itk pipelines to accomplish specific slicer tasks (such as resampling volumes for display)
• GUI classes can depend on MRML and Logic and KWWidgets
• Wherever possible, GUI functionality should be encapsulated as subclasses of vtkKWCompositeWidget with no dependence on MRML or Logic
• GUI classes serve as the mediator between the Logic and MRML classes on one side and the 'pure UI and visualization' code in KWWidgets and VTK on the other side.

GUI style guidelines (just a start!...)

• Use grooved relief for frames to clarify functional groupings of widgets; otherwise use no (flat) relief.
• Try to allow Slicer's Theme to prescribe look and feel; only override if necessary.
• Wherever possible, use xpad = ypad = 2 between widgets; use xpad = ypad = 1 to tightly group related widgets.
• Capitalize the first letter in any text specified for a label or button.
• Try to use brief phrases when specifying text for a label or button rather than using sentences or sentence fragments ( use "Load Volumes" instead of "Choose a volume to load")
• Provide fully descriptive tool tips with each widget defined.
• Slicer's main GUI panel's dimensions are defined in slicer3/Base/GUI/vtkSlicerGUILayout.cxx; currently the GUI panel minimum width is set to 300 pixels; widgets wider than this will be clipped in Slicer's default window configuration.
• Event(keyboard accelerators and mouse actions) binding conventions are described here.

Development Practices

• While developing code, enable VTK_DEBUG_LEAKS in your vtk build and be sure to clean up any leaks that arise from your contributions.

Coordinate Systems

• World space for 3D Views is in RAS (Right Anterior Superior) space
• All units are expressed in Millimeters (mm)