KWWidgets/Projects/UIDesigner/KWWidgetsCodingStyle: Difference between revisions

From KitwarePublic
Jump to navigationJump to search
 
(6 intermediate revisions by the same user not shown)
Line 9: Line 9:
:<u><b>Abbreviations</b></u>
:<u><b>Abbreviations</b></u>
::Avoid using abbreviated words, as it is hard to read or pronounce.
::Avoid using abbreviated words, as it is hard to read or pronounce.
::For example: writte vtkKWMyLocalVariableNamedAlpha instead of vtkKWMyLclVrBlNmdAlph.
::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'.<br><br>
::Abbreviations can be used, but it should be entirely in capital letters, for example vtkLODActor, where LOD means 'Level Of Detail'.<br><br>


:<u><b>Local variables</b></u>
:<u><b>Local variables</b></u>
::Their name MUST begin with a lowercase letter.
::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.
::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.
::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.''<br><br>
::''Note: In VTK only pre-processor variables, written ALL in capital letters, use the underscore to separate words.''<br><br>


:<u><b>The class pointer 'this'</b></u>
:<u><b>The class pointer 'this'</b></u>
::ALWAYS explicit the 'this' pointer for EVERY occurrence of a class member variable and/or method.
::ALWAYS explicit the 'this' pointer for EVERY occurrence of a class member variable and/or method.
::For example: this->vtkKWMyClassMemberVar or this->vtkKWMyClassSomeMethod().<br><br>
::For example: this->vtkKWMyClassMemberVar or this->vtkKWMyClassSomeMethod().<br><br>
:<u><b>Lines' length</b></u>
::Watch for the length of your lines. As a pointer don not go beyond 78 characters per line.<br><br>


:<u><b>Comments</b></u>
:<u><b>Comments</b></u>
::When using the C/C++ single-line comment style, place a space after the two slashes.
::When using the C/C++ single-line comment style, place at least ONE space after the two slashes.
 
::For example:
::For example:
:::// The word comment commes from the late
:::// The word comment commes from the late
:::// Latin word 'commentum', meaning interpretation
:::// Latin word 'commentum', meaning interpretation
:::// ....<br><br>
:::// ....<br><br>
::Avoid placing your comments at the end of the lines of a statement. Place them <u>above</u> 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();<br><br>
::Comments at the end of statements' lines are not much used in VTK/KWWidgets<br><br>


:<u><b>Methods/Functions Delimitation</b></u>
:<u><b>Methods/Functions Delimitation</b></u>
::Delimit the begining of each class method by placing a separator before each implementation. This helps readability of the code.
::Delimit the begining of each class method by placing a separator before each implementation. This helps readability of the code.
::For example:
::For example:
:://--------------------------------------------
:://--------------------------------------------
Line 73: Line 94:
:<u><b>Forward declaration</b></u>
:<u><b>Forward declaration</b></u>
::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.
::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:
::For example use:
::: #include <vtkKWApplication.h>
::: #include <vtkKWApplication.h>
Line 87: Line 109:
:::    vtkKWYourExistingBethaClass* Beta;
:::    vtkKWYourExistingBethaClass* Beta;
:::    vtkKWYourExistingPhiClass* Phi;
:::    vtkKWYourExistingPhiClass* Phi;
::Instead of the "classic":
::Instead of the "classic":
::: #include <vtkKWApplication.h>
::: #include <vtkKWApplication.h>
Line 107: Line 130:
:<u><b>The 'bool'-ean type</b></u>
:<u><b>The 'bool'-ean type</b></u>
::Do not use 'bool' in the header files, as it can not be wrapped properly. This is IMPORTANT. Use 'int' instead.
::Do not use 'bool' in the header files, as it can not be wrapped properly. This is IMPORTANT. Use 'int' instead.
::For example use:
::For example use:
:::int isMyPropertySet(); // Returns 1 if my property is set, else it returns 0
:::// Returns 1 if my property is set, else it returns 0
:::int isMyPropertySet();
 
::Instead of:
::Instead of:
:::bool isMyPropertySet(); // Returns true if my property is set, else it returns false
:::// 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.<br><br>
::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.<br><br>
:<u><b>The VTK error, debug and warning macros</b></u>
::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.<br><br>
:<u><b>Single-line execution blocks</b></u>
::Avoid omiting curly braces for single-line execution blocks. It might lead to errors, while using macros.
::For example the following:
:::if(this->vtkKWMyBooleanClassMemberVariable == false) this->vtkKWMyBooleanClassMemberVariable = true;
::Should be written as:
:::if(this->vtkKWMyBooleanClassMemberVariable == false)
:::&nbsp;&nbsp;{
:::&nbsp;&nbsp;this->vtkKWMyBooleanClassMemberVariable = true;
:::&nbsp;&nbsp;}<br><br>
:<u><b>std and STL objects</b></u>
::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.<br><br>
:<u><b>The vtkSetGet.h header</b></u>
::One doesn't need to include this header file, as it is automatically included.<br><br>

Latest revision as of 03:35, 27 May 2006

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 curly braces for single-line execution blocks. It might lead to errors, while using macros.
For example the following:
if(this->vtkKWMyBooleanClassMemberVariable == false) this->vtkKWMyBooleanClassMemberVariable = true;
Should be written as:
if(this->vtkKWMyBooleanClassMemberVariable == false)
  {
  this->vtkKWMyBooleanClassMemberVariable = 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.