TiGL Programmers Guide

Topics

• [TiGL Style Guide](#TiGL Mandatory C++ Style Guidelines)
• Git workflow

TiGL Mandatory C++ Style Guidelines

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

There is a nice code format tool, called Artistic Style (http://astyle.sourceforge.net/). It can be completely adapted to the TiGL style guidelines.

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

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.

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

Use proper commits messages for automatic change log creation

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 requests for contributors

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