libvlfeat: Developing the library

This page contains information useful to the developer of VLFeat.

Copyright

A short copyright notice is added at the beginning of each file. For example:

Copyright (C) 2013 Milan Sulc
Copyright (C) 2012 Daniele Perrone.
Copyright (C) 2011-13 Andrea Vedaldi.
All rights reserved.

This file is part of the VLFeat library and is made available under
the terms of the BSD license (see the COPYING file).

The copyright of each file is assigned to the authors of the file. Every author making a substantial contribution to a file should note its copyright by adding a line to the copyright list with the year of the modification. Year ranges are acceptable. Lines are never deleted, only appended, or potentially modified to list more years.

Coding style

Look at existing code before you start. The general rule is: try to match the style of the existing code as much as possible.
No white spaces at the end of lines. White spaces introduce invisible changes in the code that are however picked up by control version systems such as Git.
Descriptive variable names. Most variable names start with a lower case letter and are capitalized, e.g., numElements. Only the following abbreviations are considered acceptable: num. The dimension of a vector is the number of elements it contains (for other objects that could be a size, a length, or a numElements). For multi-dimensional arrays, dimensions could indicate the array with each of the numDimensions dimensions.
Short variable names. For indexes in short for loops it is fine to use short index names such as i, j, and k. For example:
```
for (i = 0 ; i < numEntries ; ++i) values[i] ++ ;
```
is considered acceptable.
Function arguments. VLFeat functions that operate on an object (member functions) should be passed the object address as first argument; this argument should be called self. For example:
```
   void vl_object_do_something(VlObject *self) ;
```
Multi-dimensional arrays should be specified first by their address, and then by their dimensions. For example
```
  void vl_use_array (float * array, vl_size numColumns, vl_size numRows) ; // good
  void vl_use_array (vl_size numColumns, vl_size numRows, float * array) ; // bad
```
Arguments that are used as outputs should be specified first (closer to the left-hand side of an expression). For example
```
 void vl_sum_numbers (float * output, float input1, float input2) ; // good
 void vl_sum_numbers (float input1, float input2, float * output) ; // bad
```
These rules can be combined. For example
```
 void vl_object_sum_to_array (VlObject * self, float * outArray,
        vl_size numColumns, vl_size numRows, float * inArray) ; // good
```
Note that in this case no dimension for inArray is specified as it is assumed that numColumns and numRows are the dimensions of both arrays.

MATLAB coding style

Help messages. Each .m file should include a standard help comment block (accessible from MATLAB help() command). The first line of the block has a space, the name of the function, 4 spaces, and a brief command description. The body of the help message is indented with 4 spaces. For example
```
% VL_FUNCTION    An example function
%    VL_FUNCTION() does nothing.
```
The content HELP message itself should follow MATLAB default style. For example, rather than giving a list of formal input and output arguments as often done, one simply shows how to use the function, explaining along the way the different ways the function can be called and the format of the parameters.

Documenting the code

The VLFeat C library code contains its own in documentation Doxygen format. The documentation consists in generic pages, such as the index and the page you are reading, and documentations for each library module, usually corresponding to a certain header file.

**Inline comments.** Inline Doxygen comments are discouraged except in the documentation of data members of structures. They start with a capital letter and end with a period. For example:
```
  struct VlExampleStructure {
    int aMember ; /\*\*< A useful data member.
  }
```

**Brief comments.** Brief Doxygen comments starts by a capital and end with a period. The documentation of all functions start with a brief comment.

Documenting the library modules

A library module groups a number of data types and functions that implement a certain functionality of VLFeat. The documentation of a library module is generally organized as follows:

1. A page introducing the module and including a getting started section (3.g. Getting started) containing a short tutorial to quickly familiarize the user with the module (e.g. Support Vector Machines (SVM)). 2. One or more pages of detailed technical background discussing the algorithms implemented. These sections are used not just as part of the C API, but also as documentation for other APIs such as MATLAB (e.g. SVM fundamentals). 3. One or more pages with the structure and function documentation (e.g. svm.h).

More in detail, consider a module called Example Module. Then one would typically have:

A header or declaration file example-module.h. Such a file has an heading of the type:
This comment block contains a file directive, causing the file to be included in the documentation, a brief directive, specifying a short description of what the file is, and a list of authors. A (non-Doxygen) comment block with a short the copyright notice follows. The brief directive should include a @ref directive to point to the main documentation page describing the module, if there is one.
An implementation or definition file example-module.c. This file has an heading of the type:
This is similar to the declaration file, except for the content of the brief comment.

Documenting functions

Documenting structures

As seen in Objects, VLFeat treats certain structures with an object-like semantics. Usually, a module defines exactly one such objects. In this case, the object member functions should be grouped (by using Doxygen grouping functionality) as

**Construct and destroy** for the vl_object_new, vl_object_delete and similar member functions.
**Set parameters** for setter functions.
**Retrieve parameters and data** for getter functions.
**Process data** for functions processing data.

Bibliographic references

Since version 0.9.14, the VLFeat C library documentation makes use of a proper bibliographic reference in BibTeX format (see the file docsrc/vlfeat.bib). Doxygen uses this file when it sees instances of the @cite{xyz} command. Here xyz is a BibTeX key. For example, vlfeat.bib file contains the entry:

@inproceedings{martin97the-det-curve,
	Author = {A. Martin and G. Doddington and T. Kamm and M. Ordowski and M. Przybocki},
	Booktitle = {Proc. Conf. on Speech Communication and Technology},
	Title = {The {DET} curve in assessment of detection task performance},
	Year = {1997}}

For example, the Doxygen directive @cite{martin97the-det-curve} generates the output [martin97the-det-curve]}, which is a link to the corresponding entry in the bibliography.