C. Coding Standards

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.

• See VXL Philosophy.
• See VCL Requirements.
• See CMake Build System.

• All code should build, preferably warning-free, on the platforms on our dashboard. This is probably the single most important coding standard. If your commit breaks an existing build, you are responsible for fixing it as quickly as possible. If you don't understand the error, contact the relevant platform's maintainer for help.
• The code should have good coverage with regression testing, and no reported memory leaks, etc.
• Anyone who is modifying code should keep a watch on the vxl-maintainers email list.

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.

• All global scope identifiers are lowercase with underscores separating words. (Rejected vxl_Image_template by vote Zurich, March 2001.)
• Each class, file, function and member variable should have a one line Doxygen description (brief line) in addition to the optional long description. See core/doc/vxl_doc_rules.* for further information. Each library should have a file in its directory called introduction_doxy.txt, containing at least the following:

  /*! \mainpage wibble: Succinct Description of wibble. */

• Private member variables should have a underscore as a suffix, e.g. value_. (An underscore as a prefix _value is not allowed by the C++ standard. Rejected by vote: prefix "m_", e.g. m_value.)
• Accessor functions for a variable x_ should be called x() and set_x(). In particular

  T x; ... void set_x(T x); // or const T&, or whatever T x();

  (Using get_x() is redundant and simply causes extra typing.) set_x() should return void. (It should never return the old value, as this can be highly confusing.)

  void x(T val) { x_ = val; } // WRONG!

• Any forward declarations in a library val should be consolidated in val_fwd.h at the top level of the library. However, there is no requirement to provide forward declarations.
• A file may have more than one class, provided they "belong". The goal of the filename=class name is to make it easy to find class/function declarations and definitions. As long as this holds, a file may declare more than one class.
• One tab (0x08) *always* expands to 8 spaces
• Indentation:
  • may use any number of indent spaces (>=2), but must be consistent.
  • we rejected proposal to fix the number of indent spaces
  • may only use spaces for indentation (i.e. no tab characters, which means 10 spaces of indentation may *not* be replaced by one tab and two spaces). (Reason: Visual Studio (and other editors) allow the developer to set tab=n. Most people have done this to their own taste. These environments convert TAB to n spaces, instead of 8.)
  • When editing other people's sources, you must use the same indentation as they have.
• Maximum number of characters per line: 132. (Number extracted primarily from vtk guidelines). 80 character lines preferred when possible.
• Source file endings:
  • C source files should end .c
  • C++ ordinary source files should end in .cxx
  • Header files should end in .h
  • C++ Template implementation code should end in .txx

  (These choices minimise problems and maximise sensible default behaviour over many compilers. Agreed by consensus on vxl-maintainers May 2002.)

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.

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

• All the "should"s in the above standards, will need to be treated as "must"s, unless there is a good reason.
• A second institution or company, must be happily using your library. (It is unclear whether that second institution needs to be a well known member of the VXL community.) The second institution may well be the one pushing for the library's elevation to the core.
• There must be a texinfo chapter for the VXL book, that provides a beginners introduction and tutorial to the library.
• There must be a designated owner for the library, who is responsible for co-ordinating changes to that library.

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.

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.

This document was generated on May, 1 2013 using texi2html 1.76.