Documentation/Nightly/Developers/Style Guide - Revision history

Lasso: Moved to readthedocs

2022-03-15T20:32:37Z

Moved to readthedocs

2020-10-16T15:00:30Z

Naming

2020-10-16T14:57:15Z

Naming

2020-03-30T22:09:51Z

Commits: Accept DOC: as a valid prefix. See discussion at https://github.com/Slicer/Slicer/pull/4783#issuecomment-606277518

2020-02-21T03:53:13Z

String encoding: UTF-8 everywhere

2020-02-21T03:52:23Z

Error and warning messages

2016-07-04T18:06:24Z

Misc.

2016-06-17T23:09:39Z

Commits

2016-06-17T20:03:25Z

Importing changes from external project/repository

2014-12-16T02:50:47Z

Logging

@@ Line 17: / Line 17: @@
 #: "Millimeter" not "Millimetre"
 #: "Color" not "Colour"
-# Use GetNumberOfXXX in VTK classes, and XXXCount in Qt classes
+# Follow VTK naming conventions in VTK classes and Qt conventions in Qt classes. For example:
 == Comments ==

@@ Line 17: / Line 17: @@
 #: "Millimeter" not "Millimetre"
 #: "Color" not "Colour"
 == Comments ==

@@ Line 171: / Line 171: @@
 * Use the [[#Message_content|body to explain]] what and why vs. how
 ** If there was important/useful/essential conversation or information, copy or include a reference
-* [[#Commit_message_prefix|Prefix]] the commit message title with "BUG:","ENH:","COMP:", "STYLE:". Note the ':' (colon) character.
+* [[#Commit_message_prefix|Prefix]] the commit message title with "BUG:", "COMP:", "DOC:", "ENH:", "STYLE:". Note the ':' (colon) character.
 * When possible, one keyword to scope the change in the subject (i.e. "STYLE: README: ...", "BUG: vtkMRMLSliceLogic: ...")
@@ Line 181: / Line 181: @@
              (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).
+             (improve coding style, comments).
 Note that the ':'(colon) directly follows the commit tag. For example, it is: "STYLE:" not "STYLE :"

@@ Line 103: / Line 103: @@
    std::string ss = ...
    QString qs1 = QString::fromUtf8(ss); // this is slightly preferred, as it is very clear and explicit
-   QString qs2 = QString(ss); // it does the same as fromUtf8, it is acceptable, too, because it is a bit simpler and used throughout the code base anyway
+   QString qs2 = QString(ss); // same result as fromUtf8, acceptable, as it is a bit simpler and used throughout the code base anyway
 Conversion from QString to std::string:

@@ Line 93: / Line 93: @@
 # World space for 3D Views is in RAS (Right Anterior Superior) space. See [[Coordinate systems]].
 # All units are expressed in Millimeters (mm)
 == Error and warning messages ==

@@ Line 136: / Line 136: @@
 == Misc. ==
-# No more than 80 characters per line
+# Ideally, no more than 80 characters per line.  Keep line length under 120 characters.
 = Commits =

@@ Line 140: / Line 140: @@
 = Commits =
 ==Summary==
 #Prefix the commit message title with "BUG:","ENH:","COMP:", "STYLE:". Note the ':' (colon) character.
-#Explain in the commit message title the "impact of the commit to the user"
+* Separate the subject from body with a blank line
-#Add in the commit message body the Mantis issue number prefixed by '#' (pound) character.
+* Limit the subject line to 50 characters
 ==Commit message prefix==
@@ Line 211: / Line 219: @@
 == Resources ==
-http://www.slicer.org/slicerWiki/index.php/Slicer:git-svn
+* Read more on [http://chris.beams.io/posts/git-commit/ How to Write a Git Commit Message]
 = UI Design Guidelines =

@@ Line 186: / Line 186: @@
 ==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.
+When you update the git tag or svn revision of any external project, explain 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 ininteligible messages:
+This will avoid having a Slicer commit history made of unintelligible messages:
   r19180 - ENH: Update git tag
   r19181 - BUG: Update svn revision
@@ Line 194: / Line 194: @@
   ...
 Ideally it should be the same message than the commit(s) in the external repository.
 Example:
 {{pre2|<nowiki>
-COMP: Update MultiVolumeExplorer project to fix
+COMP: Update MultiVolumeExplorer to fix unused-local-typedefs warnings
 $ git shortlog 17a9095..d68663f --no-merges
@@ Line 206: / Line 207: @@
        COMP: Fix unused-local-typedefs warnings
 </nowiki>}}
 See http://viewvc.slicer.org/viewvc.cgi/Slicer4?view=revision&revision=23377
 == Resources ==

@@ Line 220: / Line 220: @@
 The following log levels are used in Slicer:
 * Error: detected errors, conditions that should never occur
-* Warning: potential errors
+* Warning: potential errors, possible computation inaccuracies
 * Info: important events, application state changes (helps to determine what the steps lead to a certain error or warning); one user action should not generate more than 1-2 info level messages
 * Debug: any information that may be useful for debugging and troubleshooting