KWWidgets/Projects/UIDesigner/KWWidgetsCodingStyle

VTK/KWWidgets Coding Style

    This section is a personnal and unofficial compilation of some of the coding style convention used in VTK/KWWidgets. It it based on the contents of e-mails exchanged with Sebastien Barre, the KWWidgets conceptor and main developer.

    You can find a more official source in chapter 9, Contributing Code, of the VTK User's Guide book.

    That being said here is the list:

Abbreviations

Avoid using abbreviated words, as it is hard to read or pronounce.

For example: writte vtkKWMyLocalVariableNamedAlpha instead of vtkKWMyLclVrBlNmdAlph.

Abbreviations can be used, but it should be entirely in capital letters, for example vtkLODActor, where LOD means 'Level Of Detail'.

Local variables

Their name MUST begin with a lowercase letter.

To separate words either use an underscore, or capitalize the first letter of each new word. For example: my_local_variable_alpha or myLocalVariableAlpha.

Barre *honours* best the first approach in KWWidgets.

Note: In VTK only pre-processor variables, written ALL in capital letters, use the underscore to separate words.

The class pointer 'this'

ALWAYS explicit the 'this' pointer for EVERY occurrence of a class member variable and/or method.

For example: this->vtkKWMyClassMemberVar or this->vtkKWMyClassSomeMethod().

Lines' length

Watch for the length of your lines. As a pointer don not go beyond 78 characters per line.

Comments

When using the C/C++ single-line comment style, place at least ONE space after the two slashes.

For example:

// The word comment commes from the late

// Latin word 'commentum', meaning interpretation

// ....

Avoid placing your comments at the end of the lines of a statement. Place them above the line in question.

For example instead of:

this->vtkKWMyClassVar->vtkKWMyClassMethodAlpha(); // this statement calls the vtkKWMyClassMethodAlpha

Write it like this:

// this statement calls the vtkKWMyClassMethodAlpha

this->vtkKWMyClassVar->vtkKWMyClassMethodAlpha();

Comments at the end of statements' lines are not much used in VTK/KWWidgets

Methods/Functions Delimitation

Delimit the begining of each class method by placing a separator before each implementation. This helps readability of the code.

For example:

//--------------------------------------------

void vtkKWMyClass::vtkKWMyClassMyMethodAlpha()

{

std::cerr << "The 'vtkKWMyClassMyMethodAlpha()' method is being executed." << std::endl;

}

//--------------------------------------------

void vtkKWMyClass::vtkKWMyClassMyMethodBetha()

{

std::cerr << "The 'vtkKWMyClassMyMethodBetha()' method is being executed." << std::endl;

}

Use '//----' as your separator, since it is the one already used in KWWidgets.

Copyright notice

Use the following copyright notice on top of each .h and .cxx file. This is just the base *template* copyright notice.It might (or not) get modified depending on the project under development. Note: Replace vtkKWClass with the actual name of the implemented class.

/*=========================================================================

Module: $RCSfile: vtkKWClass.h,v $

Copyright (c) Kitware, Inc.

All rights reserved.

See Copyright.txt or http://www.kitware.com/Copyright.htm 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.

=========================================================================*/

File extension

Your C++ source files should have the '.cxx' extension, and your header files the '.h' extension. This is not a must, but more of an 'implicit' convention used throughout the KWWidgets files written so far.

The 'Delete' method

Avoid reimplementing the 'Delete()' class method. Everything related to destruction should be taken care of inside the class destructor.

The TCL/TK interpreter

Initialization of an TCL/TK interpreter MUST to be done BEFORE any vtkKWApplication instance variable is allocated. This inialization is done by calling the vtkKWApplication::InitializeTcl static method.

Forward declaration

In your header files, do not include the headers of the classes you are using as member. Instead of that you should forward-declare them. This technique allows faster compilations, because only the super-class header file is included. It also reduces a lot the set of dependencies, meaning that the depencencies check are much faster, and if you modify any of those other header files, less files will get recompiled.

For example use:

#include <vtkKWApplication.h>

class vtkKWWindow;

class vtkKWSplashScreen;

class vtkKWYourExistingBethaClass;

class vtkKWYourExistingPhiClass;

class vtkKWYourAlphaClass : public vtkKWApplication

{

protected:

vtkKWWindow* MainWindow;

vtkKWSplashScreen* SplashScreen;

vtkKWYourExistingBethaClass* Beta;

vtkKWYourExistingPhiClass* Phi;

Instead of the "classic":

#include <vtkKWApplication.h>

#include <vtkKWWindow>

#include <vtkKWSplashScreen>

#include "vtkKWYourExistingBethaClass.h"

#include "vtkKWYourExistingPhiClass.h"

class vtkKWYourAlphaClass : public vtkKWApplication

{

protected:

vtkKWWindow* MainWindow;

vtkKWSplashScreen* SplashScreen;

vtkKWYourExistingBethaClass* Beta;

vtkKWYourExistingPhiClass* Phi;

The New-Delete 'compensation'

For EVERY instace variable created using the New() method, you MUST use its counter-part Delete() method. This is necessary to balance the reference count of objects. Objects are ONLY deleted from memory, the moment their reference count equals zero. So this 'compensation' avoids memory leaks.

The 'bool'-ean type

Do not use 'bool' in the header files, as it can not be wrapped properly. This is IMPORTANT. Use 'int' instead.

For example use:

// Returns 1 if my property is set, else it returns 0

int isMyPropertySet();

Instead of:

// Returns true if my property is set, else it returns false

bool isMyPropertySet();

You can use 'bool' in your .cxx files, if you need to, especially if you use the STL for your datastructure --STL utilization is strongly recommend by Barre--, but in one should normally use 'int' for standard boolean operations.

The VTK error, debug and warning macros

Take advantage of the 'vtkErrorMacro', 'vtkDebugMacro', 'vtkWarning' macros, defined in the 'vtkSetGet.h' VTK header file, to indicate error, debug and/or warning messages inside your classes.

Besides the advantages of using pre-defined macros, you will benefit from the fact that you can simply turn ALL these message on and off by conviniently calling the 'vtkObject::SetGlobalWarningDisplay()' static method.

Single-line execution blocks

Avoid omiting brackets for single-line execution blocks. It might lead to errors, while using macros.

For example the following:

if(this->vtkKWMyClassMyMemberBooleanVariable == false) this->vtkKWMyClassMyMemberBooleanVariable = true;

Should be written as:

if(this->vtkKWMyClassMyMemberBooleanVariable == false)

  {

  this->vtkKWMyClassMyMemberBooleanVariable = true;

  }

std and STL objects

Instead of using the standard std and STL objects use their VTK wraps, e.g. vtksys_stl::string instead of std::string. These wraps are found in <VTK-Build-Folder>/Utilities/vtksys directory and they include the actual std/STL headers, besides other special manipulations.

The vtkSetGet.h header

One doesn't need to include this header file, as it is automatically included.