Documentation/4.0/Developers/Style Guide

From Slicer Wiki
Revision as of 12:33, 27 March 2012 by Kikinis (talk | contribs)
Jump to: navigation, search
Home < Documentation < 4.0 < Developers < Style Guide

Code style

C++ coding style

Documentation/4.0/Developers/Slicer_C++_Style_Guide

Python coding style

Commits

Commit message prefix

Subversion Commits to Slicer require commit type in the comment. Valid commit types are: 

  BUG:   - a change made to fix a runtime issue
           (crash, segmentation fault, exception, or incorrect result,
  COMP:  - a fix for a compilation issue, error or warning,
  ENH:   - new functionality added to the project,
  PERF:  - a performance improvement,
  STYLE: - a change that does not impact the logic or execution of the code.
           (improve coding style, comments, documentation).

The Subversion command to commit the change is: 

 svn commit -m "BUG: fixed core dump when passed float data" filename1[, filename2, ...]

By using the -m command line option, it's not possible to submit a message having multiple line. Submitting a mutli-line message can be achieved using the -f option: 

 svn commit -f /path/to/message filename1[, filename2, ...]

It's also possible to set the environment variable SVN_EDITOR

Message content

A good commit message title (first line) should explain what the commit does for the user, not how it is done. How can be explained in the body of the commit message (if looking at the code of the commit is not self explanatory enough).

Examples

  • Bad: BUG: Check pointer validity before dereferencing -> implementation detail, self-explanatory (by looking at the code)
  • Good: BUG: Fix crash in Module X when clicking Apply button
  • Bad: ENH: More work in qSlicerXModuleWidget -> more work is too vague, qSlicerXModuleWidget is too low level
  • Good: ENH: Add float image outputs in module X
  • Bad: COMP: Typo in cmake variable -> implementation detail, self-explanatory
  • Good: COMP: Fix compilation error with Numpy on Visual Studio

If the commit is related to a mantis issue (bug or feature request), you can mention it in the commit message body: 

BUG: Fix crash in Volume Rendering module when switching view layout

vtkSetAndObserveMRMLNodeEventsMacro can't be used for observing all types of vtkObjects,
only vtkMRMLNode is expected by vtkMRMLAbstractLogic::OnMRMLNodeModified(...) 
Closes #1641

Where 1641 refers to the issue number in mantis

Importing changes from external project/repository

When you update the git tag or svn revision of any external project, explicit in the commit message what the update does instead of just mentioning that an update in made.

This will avoid having a Slicer commit history made of ineligible messages: 

r19180 - ENH: Update git tag
r19181 - BUG: Update svn revision
r19182 - ENH: revision updated
...

Ideally it should be the same message than the commit(s) in the external repository.

Example: ENH: Add feature A in module X instead of ENH: Update git tag

Resources

http://www.na-mic.org/Wiki/index.php/Engineering:Subversion_Repository

http://www.slicer.org/slicerWiki/index.php/Slicer:git-svn

GUI and Usability

GUI guidelines

Retrieved from "https://www.slicer.org/w/index.php?title=Documentation/4.0/Developers/Style_Guide&oldid=25163"