We had a discussion today about SMTK’s coding standards (including documentation style). Here is a summary of what we are proposing as a “standard”.
Whitespace
- No tabs will be in source files. All tabs should be converted to 2 spaces
- All blocks should be indented by 2 spaces
- Source files should not contain trailing whitespaces at the ends of lines.
- Source files should end with a new line and should not contain any additional blank lines at the end of the file.
File Names
In SMTK you will encounter the following file sufixes:
- .h - C++ Header File
- .cxx - C++ Source File
- .txx - C++ Template File
Header Files
- All header files should include a copy of the SMTK copyright boilerplate at the top of the file:
//=========================================================================
// Copyright (c) Kitware, Inc.
// All rights reserved.
// See LICENSE.txt for details.
//
// This software is distributed WITHOUT ANY WARRANTY; without even
// the implied warranty of MERCHANTABILITY or FITNESS FOR A PARTICULAR
// PURPOSE. See the above copyright notice for more information.
//========================================================================= - Followed by the appropriate header guard with the following format:
- Concatenation of all of the namespaces (each separated by a ‘_’, followed by the name of the file with the .h replaced by _h.
- Example: a file called Foo.h under namespaces smtk, attribute would have a guard called: smtk_attribute_Foo_h
- Exception - when dealing with Pybind files, the guard starts with the pybind.
- Example: a pybind file name PybindFoo.h under namespaces smtk, attribute would have a guard called: pybind_smtk_attribute_Foo_h
- Concatenation of all of the namespaces (each separated by a ‘_’, followed by the name of the file with the .h replaced by _h.
- Followed by a blank line
Include Files
- If the file is a derived class, the next thing should be the appropriate include file followed by a newline.
- If the header needs additional include files, they should then be listed afterwards in alphabetical order. If you want to group them differently, separate them into groups separated by blank lines. Each group should be arranged alphabetically.
Note: when possible, please use forward declarations over an include file for the header.
Export Macros
Since we support all platforms its important to do appropriate declspec’ing (especially for Windows).
Make sure you are using the appropriate export macro for your classes and functions. For example SMTKCORE_EXPORT is used for all classes in the core SMTK library.
Inline Functions/Methods
If the function is a couple lines long you can add the implementation with the declaration; however, complex functions should be implemented at the bottom of the file.
Do not use “using namespace”
Do not use using namespace … in the header file since this will leak out into the file that contains it. Though namespace aliases are permitted.
Naming Conventions
- All class names start with an upper case letter and are in camel case format:
- Example: MyAttributeClass
- All class member functions start with a lower case letter and are in camel case format
- Example: myMemberFunction
- All class instance variable start with m_ followed by a lower case letter and is in camel case format
- Example: m_myInstanceVariable
- All class variables start with s_ followed by a lower case letter and is in camel case format
- Example: s_myClassVariable
- All static variables start with s_ followed by a lower case letter and is in camel case format
- Example: s_myStaticVariable
- All global variables start with g_ followed by a lower case letter and is in camel case format
- Example: g_myGlobalVariable. Note: Please try to avoid using globals in SMTK Library Source Files.
- Namespace Conventions
- A namespace should be all lower case
- All SMTK related functionality should be under the smtk namespace
- Nested namespaces further classifies the functionality being added to SMTK and tends to reflect the directory structure of the source code.
Exception to Naming Conventions
Besides functionality that is solely related to SMTK, the SMTK code base also extends the functionality of other open source efforts such as VTK and ParaView. In order to make it easy to transition files from these SMTK extensions into these open source projects, these files may adhere not to SMTK’s naming/coding conventions, but to the related open source library they are extending. So for example, if you are creating a VTK filter under smtk/extension/vtk and you feel that it could be upstreamed to VTK in the future, you should be using the VTK naming and coding conventions. The following is a set of prefix guidelines:
- Files that begin with pq or qt extends ParaView Qt functionality and may follow Qt coding style.
- Files that begin with vtk extend VTK functionality and may follow VTK coding style.
Other Coding Guidelines
- When calling a member function, always use the this-> notation
- When calling a class static method, prefix it with the class name. So for example, calling the static method bar() for class Foo would be Foo::bar()
- Always use const if the method does not modify the instance’s non-mutable state.
- In terms of accessor methods for instance variable: Since we prefix all instance variables with m_ , then get accessors are simple the name of the variable without the m_ and the set accessor is the get accessor with the first letter capitalized and prepended with set. So for example if we have an instance variable names m_foo and we want to provide accessors for it, they would be named: foo() const for the get accessor and setFoo(…) for the set accessor.
Documentation Comments
- We use Doxygen to generate documentation. The convention we have recently agreed on is to use /** … */ for all multiline documentation. If you have a simple 1 line documentation line you can use ///.
- Please include the \brief directive for the brief documentation (instead of assuming that the first paragraph is the brief documentation.
- Using grouping where appropriate.
- Document parameters if they are not intuitively named.