/builds/gitlab-kitware-sciviz-ci/Documentation/dev/git/guidelines.md
Go to the documentation of this file.
1 Guidelines
2 ==========
3 This document shows guidelines for code contributers, mainly focused on C++ code.
4 
5 Licensing
6 ---------
7 Each code file (header and source) requires SPDX license and copyright headers with a specific syntax
8 
9 ```
10 // SPDX-FileCopyrightText: Copyright (c) Kitware Inc.
11 // SPDX-License-Identifier: BSD-3-Clause
12 ```
13 
14 If a secondary copyright *must* be added, format as follows:
15 
16 ```
17 // SPDX-FileCopyrightText: Copyright (c) Kitware Inc.
18 // SPDX-FileCopyrightText: Copyright (c) NAME_OF_PERSON_OR_INSTITUTE_CONTRIBUTING_THE_CODE
19 // SPDX-License-Identifier: BSD-3-Clause
20 ```
21 
22 Please note it is not required to add your own copyright line when modifying or adding a file.
23 Even without adding it you still own copyrights on the line you modified or added in the file
24 according to the git history. Consider instead adding a `@thanks` tag in the documentation of the class.
25 
26 If the code *must* be contributed under another license than `BSD-3-Clause` license, contact
27 maintainers to find the right formalism and ensure license compatibility before contributing.
28 
29 Find more information about Software Package Data Exchange (SPDX) and Software Bill of Materials (SBOM)
30 in the VTK documentation:
31 [SPDX & SBOM](https://gitlab.kitware.com/vtk/vtk/-/blob/master/Documentation/docs/advanced/spdx_and_sbom.md)
32 
33 C++ Preprocessor
34 ----------------
35 * Use extensions .h and .cxx.
36 * Use `#include <...>` for includes of third-party headers, use `#include "..."` for includes of ParaView headers.
37 * Use no generic defines like `DEBUG`.
38 * Do not use double underscore in define or macro names, no `__MY_DEFINE`.
39 * Prefer `#if` checks on unconditionally set symbols rather than `#ifdef` checks on conditionally defined symbols.
40 
41 C++ Language
42 ------------
43 * Preferably use C++11.
44 * Use RAII, e.g. `std::array<char, 5> dat` but not `char* dat = new[5]`.
45 * Avoid `using` and write the full namespaces (e.g. `std::string`).
46 * Exceptions can be thrown, but should not leave the function as VTK (and therefore ParaView) is not exception-safe in general.
47 * You might run clang-tidy for hints, however clang-tidy is by default stricter than necessary. VTK and ParaView have their own `.clang-tidy` configuration files.
48 
49 Naming Conventions
50 ------------------
51 * Use `this->` for all member access.
52 * Use camel style for all members (functions, attributes) and start with a capital (e.g. `CapitalStart`).
53 * Don't abbreviate public functions (`GetNumberOfElements()` but not `GetNumElems()`).
54 
55 Code Formatting
56 ---------------
57 * Use separate lines for braces like
58 ```
59 if ()
60 {
61  ...;
62 }
63 ```
64 
65 * No superfluous empty lines.
66 * In the source files separate function implementations by an empty line and a line comment
67 ```
68 //-----------------------------------------------------------------------------
69 ```
70 
71 Comments
72 --------
73 * Comment any function at least briefly in the header in [Doxygen](https://www.doxygen.nl), use the [Javadoc style](https://www.doxygen.nl/manual/docblocks.html)
74 
75 ```
76 /**
77  * This comments the function
78  */
79 void TheFunction();
80 ```
81 * Use Doxygen's `@class` for a comprehensive class description (only header).
82 * Don't keep commented code.