vtk-m/docs/CodingConventions.md

### Coding Conventions ###

Several developers contribute to VTK-m and we welcome others who are
interested to also contribute to the project. To ensure readability and
consistency in the code, we have adopted the following coding conventions.
Many of these conventions are adapted from the coding conventions of the
VTK project. This is because many of the developers are familiar with VTK
coding and because we expect vtkm to have continual interaction with VTK.

  + All code contributed to VTK-m must be compatible with VTK-m’s BSD
    license.

  + Copyright notices should appear at the top of all source,
    configuration, and text files. The statement should have the following
    form. Various copyright specific details are referenced in the LICENSE.txt
    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.
//==========================================================================
```

  + The CopyrightStatement test checks all files for a similar statement.
    The test will print out a suggested text that can be copied and pasted
    to any file that has a missing copyright statement (with appropriate
    replacement of comment prefix). Exceptions to this copyright statement
    (for example, third-party files with different but compatible
    statements) can be added to LICENSE.txt.

  + All include files should use include guards. starting right after the
    copyright statement. The naming convention of the include guard macro
    is that it should be all in lower case and start with vtk_m and than
    continue the path name, starting from the inside the vtkm source code
    directory, with non alphanumeric characters, such as / and . replaced
    with underscores. The `#endif` part of the guard at the bottom of the
    file should include the guard name in a comment. For example, the
    vtkm/cont/ArrayHandle.h header contains the guard demostrated below.

    The unique use of vtk_m over vtkm is to allow auto-complete engines the
    ability to differentiate between the header guards and VTKM_ macros
    that are used within the code base.

```cpp
#ifndef vtk_m_cont_ArrayHandle_h
#define vtk_m_cont_ArrayHandle_h

// All ArrayHandle code here

#endif //vtk_m_cont_ArrayHandle_h
```

  + The VTK-m toolkit has several nested namespaces. The declaration of
    each namespace should be on its own line, and the code inside the
    namespace bracket should not be indented. The closing brace at the
    bottom of the namespace should be documented with a comment identifying
    the namespace. Namespaces can be grouped as desired. The following is a
    valid use of namespaces.

```cpp
namespace vtkm {
namespace cont {
namespace detail {
class InternalClass;
} // namespace detail
class ExposedClass;
}
} // namespace vtkm::cont
```

  + Multiple inheritance is not allowed in VTK-m classes.

  + Any functional public class should be in its own header file with the
    same name as the class. The file should be in a directory that
    corresponds to the namespace the class is in. There are several
    exceptions to this rule.
      + Templated classes and template specialization often require the
        implementation of the class to be broken into pieces. Sometimes a
        specialization is placed in a header with a different name.
      + Many VTK-m toolkit features are not encapsulated in classes.
        Functions may be collected by purpose or co-located with associated
        class.
      + Although tags are technically classes, they behave as an
        enumeration for the compiler. Multiple tags that make up this
        enumeration are collected together.
      + Some classes, such as `vtkm::Vec` are meant to behave as basic
        types. These are sometimes collected together as if they were
        related typedefs. The vtkm/Types.h header is a good example of
        this.

  + The indentation style can be characterized as [Allman Style].
    With the curly brace (scope delimiter) placed on the
    following line and not-indented.

```cpp
if (test)
{
  clause;
}
```

  + Conditional clauses including loop conditionals such as for and while
    must be in braces below the conditional.
    
```cpp
for (auto v : vector)
{
  single line clause;
}
```

  + Two space indentation. Tabs are not allowed. Trailing whitespace
    is not allowed.

  + Code formatting is strictly enforced. VTK-m's [development workflow]
    includes a reformatting step that compares the formatting of new source
    code with our formatting definitions. Incompatible code can be
    automatically reformatted to be compliant. See [CONTRIBUTING.md -->
    Reformat a Topic][Reformat] for details.

[development workflow]: ../CONTRIBUTING.md#workflow
[reformat]:             ../CONTRIBUTING.md#reformat-a-topic

  + Use only alphanumeric characters in names. Use capitalization to
    demarcate words within a name (camel case). The exception is
    preprocessor macros and constant numbers that are, by convention,
    represented in all caps and a single underscore to demarcate words.

  + Namespace names are in all lowercase. They should be a single word that
    designates its meaning.

  + All class, method, member variable, and functions should start with a
    capital letter. Local variables should start in lower case and then use
    camel case. Exceptions can be made when such naming would conflict with
    previously established conventions in other library. (For example,
    `make_Vector2` corresponds to make pair in the standard template
    library.)

  + Always spell out words in names; do not use abbreviations except in
    cases where the shortened form is widely understood and a name in its
    own right (e.g. OpenMP).

  + Always use descriptive names in all identifiers, including local
    variable names. Particularly avoid meaningless names of a few
    characters (e.g. `x`, `foo`, or `tmp`) or numbered names with no
    meaning to the number or order (e.g. `value1`, `value2`,...). Also
    avoid the meaningless for loop variable names `i`, `j`, `k`, etc.
    Instead, use a name that identifies what type of index is being
    referenced such as `pointIndex`, `vertexIndex`, `componentIndex`,
    `rowIndex`, `columnIndex`, etc.

  + Classes are documented with Doxygen-style comments before classes,
    methods, and functions.

  + Exposed classes should not have public instance variables outside of
    exceptional situations. Access is given by convention through methods
    with names starting with Set and Get or through overloaded operators.

  + References to classes and functions should be fully qualified with the
    namespace. This makes it easier to establish classes and functions from
    different packages and to find source and documentation for the
    referenced class. As an exception, if one class references an internal
    or detail class clearly associated with it, the reference can be
    shortened to `internal::` or `detail::`.

  + Use `this->` inside of methods when accessing class methods and
    instance variables to distinguish between local variables and instance
    variables.

  + Include statements should generally be in alphabetical order. They can
    be grouped by package and type.

  + Namespaces should not be brought into global scope or the scope of any
    VTK-m package namespace with the `using` keyword. It should also be
    avoided in class, method, and function scopes (fully qualified
    namespace references are preferred).

  + All code must be valid by the C++14 specifications. It must also
    compile with Microsoft Visual Studio 2015.

  + New code must include regression tests that will run on the dashboards.
    Generally a new class will have an associated "UnitTest" that will test
    the operation of the test directly. There may be other tests necessary
    that exercise the operation with different components or on different
    architectures.

  + All code must compile and run without error or warning messages on the
    nightly dashboards, which include Windows, Mac, and Linux.

  + Do not use the base C types like `float`, `double`, `int`, `long`, etc.
    When appropriate, use templates to determine the correct type.
    Otherwise, use types defined by VTK-m. Use `vtkm::Id` or
    `vtkm::IdComponent` for indices and sizes. Consider using
    `vtkm::FloatDefault` makes sense. Otherwise, use one of VTK-m's types
    do be explicit about the data type. These are `vtkm::Int8`,
    `vtkm::UInt8`, `vtkm::Int16`, `vtkm::UInt16`, `vtkm::Int32`,
    `vtkm::UInt32`, `vtkm::Float32`, `vtkm::Int64`, `vtkm::UInt64`, and
    `vtkm::Float64`.

  + All functions and methods defined within the VTK-m toolkit should be
    declared with `VTKM_CONT`, `VTKM_EXEC`, or `VTKM_EXEC_CONT`.

We should note that although these conventions impose a strict statute on
VTK-m coding, these rules (other than those involving licensing and
copyright) are not meant to be dogmatic. Examples can be found in the
existing code that break these conventions, particularly when the
conventions stand in the way of readability (which is the point in having
them in the first place).

[Allman Style]:  https://en.wikipedia.org/wiki/Indent_style#Allman_style