SMTK Coding Standards

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
  • 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.

@johnt @dcthomp @aron.helser @Ryan_Krattiger @Stan_Hammon @C_Wetterer-Nelson @ben.boeckel @chart3388

Hi All - I’m not quite done but this is a start. let me know what you think.

Things that might need to be added (that may or may not be correct based on my impressions):

Namespaces

  • all lower case
  • namespaces mirror directory structure?

Class Names

  • exception to rule: prepending “qt” or “pq”, etc

File names

  • .h, .cxx, and .txx

Miscellaneous

  • When calling a member function from within the class, use this->foo(), not foo()
  • Use const as much as possible
  • a description of the get and set accessor function standard

@Bob_Obara

I would add that the exceptions to class names exist only in the smtk/extension directory and they are exceptions because files in those directories adopt the coding standards of the third-party libraries (VTK, Qt, ParaView) to which they add SMTK functionality.

I’ve updated the discussion with David’s and Stan’s feedback.

Privacy Notice