# 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);
    }

    #ifndef IGL_STATIC_LIBRARY
    #  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;
    }

    #ifdef IGL_STATIC_LIBRARY
    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 -lP '\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] *$" *.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" *`

See also: tutorial, auto-documentation, file formats