Difference between revisions of "Documentation/4.0/Developers/Style Guide"
m (→Comments) |
m (→Code style) |
||
Line 6: | Line 6: | ||
* Acronyms should be written in all CAPS. | * Acronyms should be written in all CAPS. | ||
− | ** | + | ** ''RASToSlice'' not ''RasToSlice'' |
− | ** ''' | + | ** ''vtkMRML'' not ''vtkMrml'' |
* Words should be spelled out and not abreviated | * Words should be spelled out and not abreviated | ||
− | ** | + | ** ''GetWindow'' not ''GetWin'' |
== Comments == | == Comments == | ||
Line 15: | Line 15: | ||
* include extensive comments in the header files | * include extensive comments in the header files | ||
* keep the comments up to date as the code changes | * keep the comments up to date as the code changes | ||
− | * use the keyword | + | * 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 | * do not leave blocks of commented out code in the source file -- if needed insert links to prior svn versions as comments | ||
Revision as of 13:55, 9 April 2012
Home < Documentation < 4.0 < Developers < Style GuideContents
Code style
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.
Naming
- Acronyms should be written in all CAPS.
- RASToSlice not RasToSlice
- vtkMRML not vtkMrml
- Words should be spelled out and not abreviated
- GetWindow not GetWin
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
Language Specific
Library Dependencies
- MRML classes should only depend on vtk and itk (not Slicer Logic or Qt)
- 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 Qt
Development Practices
- While developing code, enable VTK_DEBUG_LEAKS (ON by default) 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)
Misc.
- Use STL where you can, but follow the VTK guidelines
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
UI Design Guidelines
General guidelines
- As a general rule, follow those following guidelines:
Panels
|
Layouts
- Use the default values for the margins or 0. Default margins are automatically controlled by the Slicer custom style (see QStyle::PM_LayoutLeftMargin)
- The minimum size hint of the top level module widget is used to determine the minimum width of the module. In Qt Designer, you can ensure it's sizing is correct by changing the QLayout::SizeConstraint to QLayout::SetMinimumSize.