libigl Style Guidelines

This library is shared by many people. This document highlights some style guidelines for developers of the libigl library.

Each function prototype should be well documented. Write a summary of what the function does and a description of each template, input and output in each prototype.

Example

Here is an example function defined in include/igl/example_fun.h and implemented in include/igl/example_fun.cpp.

example_fun.h


// This file is part of libigl, a simple c++ geometry processing library.
// 
// Copyright (C) 2013 Alec Jacobson <alecjacobson@gmail.com>
// 
// This Source Code Form is subject to the terms of the Mozilla Public License 
// v. 2.0. If a copy of the MPL was not distributed with this file, You can 
// obtain one at http://mozilla.org/MPL/2.0/.
#ifndef IGL_EXAMPLE_FUN_H
#define IGL_EXAMPLE_FUN_H

#include "igl_inline.h"

namespace igl
{
  // This is an example of a function, it takes a templated parameter and
  // shovels it into cout
  //
  // Templates:
  //   T  type that supports
  // Input:
  //   input  some input of a Printable type
  // Returns true for the sake of returning something
  template <typename Printable>
  IGL_INLINE bool example_fun(const Printable & input);
}

#ifdef IGL_HEADER_ONLY
#  include "example_fun.cpp"
#endif

#endif

example_fun.cpp


// This file is part of libigl, a simple c++ geometry processing library.
// 
// Copyright (C) 2013 Alec Jacobson <alecjacobson@gmail.com>
// 
// This Source Code Form is subject to the terms of the Mozilla Public License 
// v. 2.0. If a copy of the MPL was not distributed with this file, You can 
// obtain one at http://mozilla.org/MPL/2.0/.#include "igl/example_fun.h"
#include <iostream>

template <typename Printable>
IGL_INLINE bool igl::example_fun(const Printable & input)
{
  using namespace std;
  cout<<"example_fun: "<<input<<endl;
  return true;
}

#ifndef IGL_HEADER_ONLY
template bool igl::example_fun<double>(const double& input);
template bool igl::example_fun<int>(const int& input);
#endif

General rules

Use a single .h/.cpp pair with the same name as the function
At least one version of the function should use references for all outputs
Use wrappers and additional prototypes for returning single-output functions' outputs, but the default is to only use outputs
All inputs should be const.
Use C++ references (e.g. Matrix & mat) for inputs and outputs rather than pointers (e.g. Matrix * mat) or pass-by-copy (e.g. Matrix mat).
Write multiple prototypes if you'd like to have optional parameters with default values.
External dependencies (besides Eigen and OpenGL) are only allowed within extras.
New extras and their dependencies must be discussed first.
Hard-to-compile or obscure external dependencies can go in the external/ directory.
Do not use the using namespace directive anywhere outside a local scope. This means never write: using namespace std; or using namespace igl; etc. at the top of a file.
Function names should either be the same as the corresponding MATLAB function or should use all lowercase separated by underscores: e.g. my_function_name
Classes should be in CamelCase
No tabs, only two spaces per indentation level
Be generous with assertions and always identify them with strings:
e.g. assert(m<n && "m must be less than n");

Specific rules

Each file should be wrapped in an ifndef compiler directive. If the file's (and function's) name is example.h, then the ifndef should always begin with IGL_, then the function/file name in all caps then _H. As in:


#ifndef IGL_EXAMPLE_H
#define IGL_EXAMPLE_H
...
#endif

Each file should begin with prototypes *without implementations* of each version of the function. All defined in the igl namespace. Each prototype should have its own comments describing what it is doing, and its templates, inputs, outputs.

Implementation should be separated from prototypes in a .cpp file.

Any includes, such as std libraries etc. should be in the .cpp file not the header .h file (whenever feasibly possible).

Be generous by templating your inputs and outputs. If you do use templates, you must document the template just as you document inputs and outputs.

Useful scripts to check style

script	Description
`grep -L IGL_INLINE *`	Find files that aren't using "IGL_INLINE"
`grep -L "namespace igl" *`	Find files that aren't using igl namespace
`grep -P '\t' *`	Find files using [TAB] character
`grep -l "^using namespace" *.cpp`	Find .cpp files that contain ^using namespace
`grep -l 'assert([^"]);' `	Find files using asserts without identifier strings
`grep -l "ifndef IGL_.[^H] $" *`	Find .h files that contain ifndef IGL_*[^H]
`grep -L "^#ifndef IGL_" *`	Find files that don't contain #ifndef IGL_
`grep -L "^This file is part of libigl" *`