[ < ] [ > ]   [ << ] [ Up ] [ >> ]         [Top] [Contents] [Index] [ ? ]

C. Coding Standards


[ < ] [ > ]   [ << ] [ Up ] [ >> ]         [Top] [Contents] [Index] [ ? ]

C.1 Coding Standards

As has been mentioned before, it is VXL's philosophy that any rules should be pragmatic. The following is a list of standards that have either been explicitly agreed, or implicitly observed, and are here to make our lives easier. If they are making life harder, then we will change them.

Of course, these standards only apply to code in the VXL repository. Although some of they may be useful, there is absolutely no need for users of VXL to follow them at all.


[ < ] [ > ]   [ << ] [ Up ] [ >> ]         [Top] [Contents] [Index] [ ? ]

C.2 Style Guide

The following vxl coding standards were originally agreed at the Zurich meeting in March 2001. They are mandatory for libraries in the core module. Even if you are not writing code which you expect to enter vxl/core, then it is still worth following these coding standards, as they have been designed to minimise confusing and help avoid potential problems.


[ < ] [ > ]   [ << ] [ Up ] [ >> ]         [Top] [Contents] [Index] [ ? ]

C.3 How to contribute a new class or library

If you have computer vision code that fits neatly into VXL platform, or a VXL-friendly interface to an external library, the VXL community would welcome your contribution.

For a single class, or few functions, it is worth seeing which existing VXL library your code might neatly fit into. Whole libraries should be added to a subdirectory of the contrib directory. See vxl/contrib. Get yourself an account on SourceForge, and we'll give you commit rights to the Subversion vxl repository.

It isn't expected that your code meet the Style Guide or Coding Standards on its first commit to the repository. But you will have to put some effort into making your code build cleanly on the dashboard as soon as possible. You should aim for your code to meet the coding standards and style guide over time.


[ < ] [ > ]   [ << ] [ Up ] [ >> ]         [Top] [Contents] [Index] [ ? ]

C.4 How to elevate a library to the core.


[ < ] [ > ]   [ << ] [ Up ] [ >> ]         [Top] [Contents] [Index] [ ? ]

C.5 On the Use of Templates

VXL makes heavy use of the C++ template mechanism. In order to ensure efficient compilation and linking a scheme has been adopted in which the declaration of each templated class is placed in a .h file, and its definition (implementation) is separated into a .txx file. The latter is only read a small number of times, when a particular instantiation of a template is created.

Each specialisation of the templated class must be compiled explicitly. This is usually done by creating an explicit instantiation in a file in the Templates subdirectory.

For example, vgl_point_2d<T> has a header file, vgl/vgl_point_2d.h, and an implementation in vgl/vgl_point_2d.txx. At the end of the latter is a macro which can be used to explicitly instantiation a particular specialisation of vgl_point_2d, together with all the associated templated functions:

 
File: vgl/vgl_point_2d.txx:
...
#define VGL_POINT_2D_INSTANTIATE(T) \ template class vgl_point_2d<T >; \
template vcl_ostream& operator<<(vcl_ostream&, const vgl_point_2d<T >&); \
template vcl_istream& operator>>(vcl_istream&, vgl_point_2d<T >&); \

To instantiate a a vgl_point_2d<double> there is a file in the a vgl/Templates directory:

 
File: vgl/Templates/vgl_point_2d+double-.cxx:

// Instantiation of vgl_point_2d<double>
#include <vgl/vgl_point_2d.txx>
VGL_POINT_2D_INSTANTIATE(double);

If you decided to use an unusual specialization, eg vgl_point_2d<my_sponge>, your code should compile cleanly, but would not link unless somewhere you explicitly instantiate the class and compile it somewhere suitable using a call:

 
  VGL_POINT_2D_INSTANTIATE(my_sponge);

When you write a new templated class (or function), you should put the implementation in a suitable .txx, together with an appropriate INSTANTIATE macro. Study examples in existing classes for more details.


[ < ] [ > ]   [ << ] [ Up ] [ >> ]         [Top] [Contents] [Index] [ ? ]

C.6 Frequently Asked Questions

Question 1

Can I import a useful third-party library into vxl/v3p?

The general rule is that v3p is for third-party libraries that are need by VXL core libraries. Getting libraries in v3p working on all platforms is a difficult and tedious task, so we want to have no more than necessary.

Question 2

I have a FindFoo.cmake module that is imports the very useful Foo library. Where can I put it?

You should submit it to the CMake project, where it will see wider use than just the VXL community. For very special cases, such as a new library needed by something in core, you can temporarily put it in config\cmake\Modules\NewCMake. However you should also submit it to CMake, and remove it from the VXL repository as soon as it becomes available in a CMake distribution.


[ << ] [ >> ]           [Top] [Contents] [Index] [ ? ]

This document was generated by Rumpelstiltskin on November, 22 2009 using texi2html 1.78.