Skip to content

TiGL Programmers Guide

Jump to bottom
Jan Kleinert edited this page Sep 24, 2019 · 19 revisions

Topics

General programming guidelines (compilers / C++ standard)

TiGL requires a C++ 11 capable compiler. All C++ 11 features can be used.

Minimum supported compiler version:

  • Windows: Visual C++ 2015
  • Linux: GCC 4.8

Recommended compilers:

  • Windows: Visual C++ 2015 64 bit
  • Linux: GCC 4.8 or higher
  • macOS: Clang 6 or higher

C++ Standard:

  • C++ 11 and older

TiGL Mandatory C++ Style Guidelines

General style

Tabs and Indentation

  • Use 4 spaces indentation. Don't use tabs!
  • Exceptions:
  • public/protected/private keywords in class definitions
  • namespace tigl
namespace tigl
{
namespace foo
{
    namespace bar 
    {
        /*some code*/
    }
}
}

Definitions and Declarations

  • Braces in new lines:
class CCPACSWingProfiles
{

private:
    double _member;
}
  • If you use several lines for a functions definition/declaration, align the function arguments horizontally
TIGL_COMMON_EXPORT TiglReturnCode tiglWingGetSegmentSurfaceArea(TiglCPACSConfigurationHandle cpacsHandle,
                                                                int wingIndex,
                                                                int segmentIndex)

Loops, If and Switch Statements

  • space before and after condition
  • Braces in the same line
if (psi.size()<=2) {
    psi.clear();
}
else {
    double psimax = psi[psi.size()-1];
}
for (size_t i = 0; i < psi.size(); i++) {
    CTiglPoint* point1 = new CTiglPoint(psi[i], 0.0, cstcurve(upperN1, upperN2, upperB, psi[i]));
}
switch (GetSymmetryAxis()) {
case TIGL_X_Y_PLANE:
    return zmax - zmin;
case TIGL_X_Z_PLANE:
    return ymax - ymin;
}

Automatic code formatting to TiGL style guide

Artistic Style

There is a nice code format tool, called Artistic Style (http://astyle.sourceforge.net/). It can be completely adapted to the TiGL style guidelines. We found, that AStyle 2.05 works best for our coding style!

The following options should be used:

--style=kr      
--break-closing-brackets
--add-brackets
--indent=spaces=4
--align-pointer=type
--align-reference=type
--max-instatement-indent=100
--pad-oper

The Beautifier plugin shipped with QtCreator supports Artistic Style, so you will be able to automatically format your code.

Important: don't use automatic formatting on files that you didn't create. Most of the time, you should only format the code by hand.

Clang-Format

The Clang-Format Tool can also be used to reformat the code to the TiGL style. Here are the settings that should comply to our style.

BasedOnStyle: LLVM
IndentWidth: 4
SortIncludes:    false
ColumnLimit:     120
AlignTrailingComments: false
AccessModifierOffset: -4
AlignConsecutiveAssignments: true
ReflowComments:  false
BraceWrapping:   
  AfterClass:    true
  AfterFunction: true
  BeforeElse: true
  BeforeCatch: true
  AfterNamespace:  true
  AfterEnum: true
BreakBeforeBraces: "Custom"
PointerAlignment: Left
AllowShortFunctionsOnASingleLine: false
NamespaceIndentation: Inner
BreakConstructorInitializersBeforeComma: true

Automatic style checking

We included a style checking tool into the TiGL source distribution. The style check can be executed via

make checkstyle

from inside the build directory. If you want to check e.g. only the tigl/src directory, enter

make checkstyle_src

Keep in mind that the style checking tool may have its own bugs an can produce false positives.

Git usage guidelines

Correct commit messages

This is the mandatory structure of each git commit:

  • A heading of maximum 50 characters. This is a short but concise description of the commit.
  • An empty line
  • A longer description of the commit, including ideas and rationals. Each line of this text may contain up to 72 characters.
  • An empty line
  • A related issue. E.g. Fixes issue #120. This is very important, as it increases the transparency of code changes. The line should contain a # sign following the issue number. Also it should containt a word like "fixed, fixes, addresses".

Here's an example of a correct commit message:

Unified interface to CAD exports

This commit unifies the interfaces to the following
file formats. BRep, IGES, and STEP.
This is done by using one common base class that defines
the interface. The private methods WriteImpl must be
implemented for the concrete writing procedure.
Also fixed some compiler warnings.

Addresses issue #122

Classification of git commits

During the release process, the commit messages are parsed and separated into five categories in order to create a change log file in restructured text format automatically. Afterwards, this file is converted to Latex and Google code wiki syntax. You should choose your commit message such, that it is correctly classified. For example the following commit message:

"Changed API function CCPACSWingGetPoint"

should be classified under the category "Changed API". The five categories and the corresponding filters are

Category Filter Buzzwords Example
Changed API Contains all buzzwords (case insensitive) 'changed', 'api' Changed API function CCPACSWingGetPoint
New API Contains all buzzwords (case insensitive) 'new', 'api' New API function CCPACSWingGetPoint
Fixes Contains any of the buzzwords (case insensitive) 'fixes', 'fixed', 'bugfix', 'bugfixes', 'fix' Fixed bug in CCPACSWingGetPoint
TiGLViewer Contains the buzzword (case insensitive, this filter superseeds all other filters) 'tiglviewer' New API function in TiGLViewer
General Changes Does not belong to the other categories Added support for VTK export

Moreover, file names and code should be displayed in monospaced fonts. This is achieved by the following filter

Filter Buzzwords
prefix 'tixi', 'tigl', 'CCPACS', 'ITigl', 'CTigl'
suffix '.sh', '.cpp', '.h', '.py', '.txt', '.tex'
contains but is not equal 'Wing', 'Fuselage'

For example the message

Changed behaviour of CCPACSWingProfile::GetUpperWire() in CCPACSWingProfile.cpp

is converted into

Changed behaviour of CCPACSWingProfile::GetUpperWire() in CCPACSWingProfile.cpp

General git guidelines

  • Use a separate branch for each feature. Merge the feature branch into master after finishing feature development.
  • Don't force git pushes (git push -f). Forcing push is evil and will probably cause armageddon. Only use, if you REALLY know what you're doing.

Pull requests

David Winterbottom described an effective way for managing pull requests. You should follow the following rules when dealing with pull requests: http://codeinthehole.com/writing/pull-requests-and-other-good-practices-for-teams-using-github

Pull request guidelines

The following guidelines should help the maintainer and the contributer to manage PRs as fast as possible. A PR should be easily reviewable and therefore should not contain too many changes at once. Here are the guidelines:

  • Each PR should be associated to an issue. This helps later, to figure out the rationals of those commits. If no issue exist, create a new one!
  • Don't put unrelated commits into one PR. This makes reviewing the changes very hard.
  • After creating a PR, don't push new commits into the branch. Only push new commits, if you are asked to change anything.
  • Please be patient :). Your commit will be merged as soon we have time.

Pull requests workflow

  1. Create a github account and fork the TiGL repository.

  2. Clone your fork of TiGL to your local machine

    git clone ...

  3. Create a separate branch (never commit to master!!!)

    git checkout -b feature/coolgui

  4. Do your normal work i.e. committing things to your branch (git add, git commit ...)

  5. Push your commits to your github account

    git push origin feature/coolgui

  6. In github, create pull request for the feature/coolgui branch

Once you started a pull request, your code will be reviewed by us. We might force you to perform some changes to e.g. fulfill our style guides or if there are any issues left in the code. Please perform the changes. In case of small changes, you can overwrite (amend) your old commit. Then force the push

git push -f origin feature/coolgui

Important: Only force pushes on "private" branches which aren't shared with other users. Never force push on master!

Clone this wiki locally