This section covers VLFeat coding and documentation styles.
Coding style
This section describes the coding style of the VLFeat library.
-
No whitespaces at the end of lines. Whitespaces introduce invisible changes in the code that are detected by control version systems such as Git. Therefore whitespaces at the end of lines must be avoided.
-
Object names. Object names are capitalized and start with the
Vlsuffix (e.g.VlSift). -
Descriptive variable names. Most variable names should start with a lower case letter and be capitalized, e.g.,
numElements. Only the following abbreviations are considered acceptable when constructing variable names:num,max,min,src,dst. Thedimensionof a vector is the number of elements it contains (for other objects that could be asize, alength, or anumElements). For multi-dimensional arrays,dimensionscould indicate the array with each of thenumDimensionsdimensions.Example variable names Example Comment maxNumElementsThe maxinum number of elements. sizeThe size of an object, for example the number of bytes in a memory block. dimensionThe dimension of a vector or array. Generally, this is the number of elements spanned by one scalar index dimensionsAn array of dimensions for a multi-dimensional array or tensor. numDimensionsThe number of dimensions of a multi-dimensional array or tensor. srcWidthThe width of a source image. -
Short variable names. For indexes in short for loops it is fine to use short index names such as
i,j, andk. For example:for (i = 0 ; i < numEntries ; ++i) values[i] ++ ;is considered acceptable.
-
Function and methods names. Function names are lowercase with words separated by underscores and start with the
vl_prefix. Methods names in particular start with the object name. Static function names local to a module start with a_vl_prefix instead.Example function and method names Example Comment vl_get_version_stringA function name. vl_sift_get_num_framesA method name for the object VlSift._vl_smoothA name of a static function local to a module. -
Code alignment. Indendtation uses two spaces (and no tabs). Explicitly aligning blocks of code across multiple lines is not encouraged.
-
Function declarations. Functions can be declared on one or multiple lines. In the latter case, the output arguments are contained in one line. Modifiers such as VL_EXPORT and VL_INLINE are contained in the output argument line. For example:
VL_EXPORT vl_bool vl_some_function () ; VL_EXPORT void vl_scalespace_delete (VlScaleSpace *self) ;
-
Function definition. Function definitions are similar to function declaration. However, they do not contain the VL_EXPORT modifier and are always in at least two lines. For example:
void vl_scalespace_delete (VlScaleSpace *self) ;
Documenting the code
Thi section describes how to document the VLFeat C library. VLFeat 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 specifid library module, usually corresponding to a certain heaader file.
Documenting the library modules
A library module groups a number of data types and functions that implement a certain functionaltiy of VLFeat. 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
@refdirective 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 declearation file, except for the content of the brief comment.
Documenting the library functions
Bibliographic references
VLFeat documentation makes use of a bibliographic reference database in BibTeX format (see the file docsrc/vlfeat.bib). Doxygen uses this file to interpret instances of the @cite xyz command, where 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}}
Then the Doxygen directive @cite martin97the-det-curve generates the output [7] , which includes a link to the corresponding entry in the bibliography.