Conventions

Conventions

The programming conventions that all BIAS-programmers should follow are:

Names for Files, Classes, Functions, Variables

• File names should be the class name that is implemented in the file, suffixes for all files are: .cpp .hh (.c for pure c)
• Class and function names start with a capital letter and use upper case letters as word separator, e.g. CornerDetector().
• Variables start with a lower case letter
• All protected class member variables and functions must end with underscore, e.g. int depth_; void InternalComputation_();
• Pointer variables should start with a "p", e.g. int *pCounter = NULL;
• Namespace: All classes and functions should belong to the namespace BIAS to avoid conflicts.

Function calls: Parameters and Returns

• Use call by reference for almost all function parameters to speed up execution (except basic types like int, char or double).
• Avoid pointers whenever possible, use call by reference, e.g. void ToGrey(Image<PixelType>& Source);
• Use const to distinguish between input and output parameters.
• Use function parameters to return function results, the exception are Yes/No-functions like Is.. which may return a bool.
• Return values should only indicate function success: negative=error, zero=OK, positive=non-critical message.

Code Formatting

• All indention with 2 spaces, no tabs.
• recommended: limit line width to 80 chars (but NOT mandatory)
• Thus please set Edit options as:

Example for MS Visual Studio settings:

• Tools -> Options -> Text Editor -> C/C++ -> Tabs:
• Indenting : Smart
• Tab size : 2
• Indent size: 2
• Insert space: x (enable)
• Tools -> Options -> Text Editor -> C/C++ -> Formatting:
• Indent braces: No!

Example for XEmacs settings:

• add (e.g. to ~/.xemacs/custom.el):

  (custom-set-variables
  ;; indention: 2 spaces, no tabs:
   '(setq-default indent-tabs-mode nil)
   '(setq-default tab-width 2)
   '(setq tab-stop-list '(2 4 6 8 10 12 14 16 18 20 22 24)) )
  

  XEmacs converts tabs to spaces with its "untabify" command.

Example for proper code formatting: In Declaration (in header):

#include <iostream>
/** @brief formatting example class description
@author Your Name */
class Foo
{
  /// @brief short function description
  void Bar();
};

Definition (in .cpp file):

void Foo::Bar()
{
  std::cout<<"hello";
}

Portability between Linux and Windows

We support MS Windows with Visual Studio (.Net 2003/7.1 and 2005/8.0) compiler and Linux with gcc (3.3.4, 4.1.2 ) compiler actually (as of 2007/09/09).

• Since BIAS is set up as a Multi-Platform library, make sure that your code compiles in Linux and Windows. Use #if(n)def _WIN32 to mark platform proprietary code.
• If you have to include any external dependencies, i.e. libraries, the dependant could should be ifdefed depending on an appropriate flag in bias_config.h which is automatically generated by the build system.

Static and shared libraries (.so/.dll)

• Windows needs explicit exports to mark each interface that should be exported into a DLL because of different linking. This dllexport/dllimport is handled through macros (see BIAS_DeclSpec.hh ), one for each library. Thus each library, function, class and (global) variable (including extern/extern "C" stuff) should be prefixed with the libname_EXPORT macro. See existing code for examples. If you create a new BIAS library you have to add the appropriate macro to BIAS_DeclSpec.hh.

Further programming rules

• Always use absolute includes starting below BIAS base dir, e.g. #include <Base/ImageUtils/ImageDraw.hh>
• Use includes only where they are necessary to reduce dependencies and compile time.
• Thus headers contain only includes for interfaces (or use forward declarations if appropriate),
• source file should contain all includes that are not required as an interface,
• All files should contain exactly one class (definition or declaration),
• do not spread classes over multiple files,
• do not implement multiple classes in one file.
• Avoid "pointer" arrays, please prefer use std::vector.
• Avoid char*, use std::string.

Const

• Use const wherever possible for all constant functions and parameters. This results in cleaner and faster code because of better compiler optimization and increases readability. In addition these interface are less error prone because side effect are avoided.
• Use const for all functions like Get.. or Is.. and assure that they are constant.
• Use const for all parameters for functions like Set.. orInit.. and assure that these parameters remain unchanged.

API - check build configuration in header

The BIAS API varies with the number of available (third party) libraries (and possibly which subdirectories were compiled). To avoid compilation and linking problems and given the user an early hint for a problem you must ifdef code that relies on special features. bias_config.h exists for this purpose. The procedure to catch these problems should be like this:

#include <bias_config>
#ifdndef BIAS_HAVE_<MYSPECIALLIB>
#  error BIAS was build without MYSPECIALLIB, please enable USE_MYSPECIALLIB and recompile BIAS.
#endif
...
// or to ifdef only certain functions:
/** minimal docu:  @author You */
class MyClass {
public:
#ifdef BIAS_HAVE_<MYSPECIALLIB>
  void Function_that_uses_myspeciallib();
#endif
...
  void Otherfunction();

Documentation

• Use the Doxygen documenting syntax for all code including classes, methods, variables, macros, defines etc.
• Give a short description of every member variable.
• When committing to the CVS repository, write what you have done, be more specific than "update", "changes" "fixed bug" or "-".
• Give a detailed summary of every class and point out which functions are the important ones. A sample Doxygen documentation block for classes:
• If you write a test for your class, which you should do, add it to the class with the "test" tag. In the documentation it will appear as "tested with MyTestFile.cpp"

/** @class TestDoxy
    @test MyTestFile.cpp
    @ingroup the group name, see module_hierarchy.dox for details (such as g_videosource...)
    @brief example to show Doxygen-syntax. A detailed description for every class is necessary!
    @author Your Name
    @date dd/mm/yyyy    
**/

• Give a brief summary for every function and every parameter/return value. Make sure which parameters are input and which are output. A sample Doxygen documentation block for member functions:

/** @brief example to show Doxygen-syntax
    @param par1 (input)
    @param par2 (output)
    @returns -1=error, 0=OK
    @author Your Name
    @date dd/mm/yyyy
**/

• Give meaningful names to variables.
• Describe all loops and algorithms in your words.
• The build system supports a "doc" target to build the documentation if doxygen and dot/graphviz are installed.

If you write a test - what you should do - include it in the Test subdirectory and add documentation of the style:

/**
   @file MyTestFile.cpp
   @brief Test my class XXX
   @relates MyClass
   @ingroup g_tests
   @author Your Name
   @date dd/mm/yyyy
*/

Examples should be located in the subdirectory Examples and with documentation: The relates tag connects the example with the class, in the documentation a link is added to the class for the example.

/**
   @example ExampleMyClass.cpp
   @class ExampleMyClass 
   @relates MyClass
   @brief Example for usage of class XX
   @ingroup g_examples
   @author Your Name
   @date dd/mm/yyyy
*/

E.g. Linux:

make doc

Windows:

nmake doc

or build

doc.vcproj (within BIAS.sln)

Debug (detailed)

• cerr, cout and printf should not be used for debugging. Please use COUT, BIASWARN, BIASERR, BIASDOUT, BIASDOUT_CLEAN instead which supports different kinds of debuglevel based output.
• in Addition deriving from BIAS__Debug allows more sophisticated flags based debugging.

We know that these rules were not followed in all parts of BIAS but we want to be more strict in the future, so please stick to these rules for all new commits.

Supervisors of students which program for BIAS and MIP are strongly urged to enforce a proper programming style by not accepting any work that does not conform.