Code guidelines

Coding conventions

  • headers in include/core_api shall not include headers from other YafaRay include dirs.
  • headers in include/core_api shall not use HAVE_* options (like '#if HAVE_EXR')
  • plugins using headers other than core_api ones need to have all libs added to their build environment for all HAVE_* options they pull in (directly or indirectly!)
  • interface functions shall not have arguments or return types which depend on configurable typedefines (such as CFLOAT, PLOAT and GFLOAT)
  • use doxygen comments to document non-obvious types, classes, interfaces and functions and their usage.

Indentation

YafaRay use Allman indentation style (see http://en.wikipedia.org/wiki/Indent_style#Allman_style).

Example:

if (a < b)
{
    something();
    somethingElse();
}

Formatting

  • use spaces, not tabs
  • recommended tab width converted into spaces is 4
  • 80 character terminals are from last century... everyone should be able to view at least 120 character long lines

Variable names

  • use comprensive variable names:
    color           -> WRONG
    diffuseColor -> CORRECT
  • use m prefix for member variables
    color               -> WRONG
    mDiffuseColor -> CORRECT

Commenting the code

YafaRay uses doxygen to generate code documentation.

Reference: http://www.stack.nl/~dimitri/doxygen/docblocks.html

 

Brief description example ( to be used on class variables):

vector3d_t camX;        //!< Camera x axis

 

Brief and long description example (to be used on class members):

/** Vector reflection.
 *  Reflects the vector onto a surface whose normal is \a n
 *  @param    n Surface normal
 *  @warning  \a n must be unit vector!
 *  @note     Lynn's formula: R = 2*(V dot N)*N -V (http://www.3dkingdoms.com/weekly/weekly.php?a=2)
 */
inline vector3d_t& vector3d_t::reflect(const vector3d_t &n)
{
    const float vn = 2.0f*(x*n.x+y*n.y+z*n.z);
    x = vn*n.x -x;
    y = vn*n.y -y;
    z = vn*n.z -z;
    return *this;
}

Versioning

"In principle, in subsequent releases, the major number is increased when there are significant jumps in functionality, the minor number is incremented when only minor features or significant fixes have been added, and the revision number is incremented when minor bugs are fixed" Wikipedia http://en.wikipedia.org/wiki/Software_versioning

Despite YafaRay never had a coherent versioning in the past, we stick to that priciple from now on.

For example:
after a 0.1.2 official release we could have a 0.1.3 release which only fix bugs on 0.1 tree and we will have a 0.2 tree for new features.