Documenting the code
-
Develop a sensibility for good-looking code. The coding style should be as uniform as possible throughoug the library. The style is specified by this set of rules. However, the quality of the code can only be guaranteed by a reasonable application of the rules and combined with one's eye for good code.
-
No whitespaces at the end of lines. Whitespaces 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
. Thedimension
of a vector is the number of elements it contains (for other objects that could be asize
, alength
, or anumElements
). For multi-dimensional arrays,dimensions
could indicate the array with each of thenumDimensions
dimensions. -
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.
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 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
@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 declearation file, except for the content of the brief comment.
Documenting the library functions
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 [9] , which is a link to the corresponding entry in the bibliography.