3DFaces
/
libigl_Martin


			
							123456789101112131415161718192021222324252627282930313233343536373839404142434445464748495051525354555657585960616263646566676869707172737475767778798081828384858687888990919293949596979899100101102103104105106107108109110111112113114115116117118119120121122123124125126127128129130131132133134135136137138139140141142143144145146147148149150151152153154155156157158159160161162163164165166167168169170171172173174175176177178179180181182183184185186187188189190191192193194195196197198
							<!DOCTYPE HTML>
<html>
  <head>
    <title>libigl - Style Guidelines</title>
    <link href="./style.css" rel="stylesheet" type="text/css">
  <body>
    <div id=container>
    <div class=article_inner>
    <a href=.><img src=libigl-logo.jpg alt="igl logo" class=center></a>
    <h1>libigl Style Guidelines</h1>
    <p>
This library is shared by many people. This document highlights some style
guidelines for <i>developers</i> of the <a href=.>libigl</a> library.
   </p>
   <p>
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. 
    </p>

    <h2>Example</h2>
    <p>
Here is an example function defined in <code>include/igl/example_fun.h</code> and
implemented in <code>include/igl/example_fun.cpp</code>.
    </p>
    <h3>example_fun.h</h3>
    <pre><code>
#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 &lt;typename Printable&gt;
  IGL_INLINE bool example_fun(const Printable & input);
}

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

#endif
    </code></pre>
    <h3>example_fun.cpp</h3>
    <pre><code>
#include "igl/example_fun.h"
#include &lt;iostream&gt;

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

#ifndef IGL_HEADER_ONLY
template bool igl::example_fun&lt;double&gt;(const double& input);
template bool igl::example_fun&lt;int&gt;(const int& input);
#endif
    </code></pre>


    <h2>General rules</h2>
    <ul>
      <li> Use a single .h/.cpp pair with the same name as the function </li>
      <li>
At least one version of the function should use references for all outputs
      </li>
      <li>
Functions with external dependencies should be a single .h file (no .cpp file)
  so it won't appear in libigl.a
      </li>
      <li>
Use wrappers and additional prototypes for returning single-output functions'
outputs, but the default is to only use outputs
      </li>
      <li> All inputs should be const when appropriate </li>
      <li>
Use c++ references for inputs and outputs rather than pointers or pass-by-copy
      </li>
      <li>
Take the time to write multiple prototypes if you'd like to have optional
parameters with default values
      </li>
      <li>
External dependencies (besides Eigen, OpenGL, etc.) are discouraged
      </li>
      <li>
External dependencies must be clearly identified at the top of each file.
      </li>
      <li>
External dependencies can go in the external/ directory
      </li>
      <li>
Do not use the using namespace directive anywhere outside a local scope. This
means never write: <code>using namespace std;</code> or <code>using namespace
igl;</code> etc. at the top of a file.
      </li>
      <li>
Function names should either be the same as the corresponding MATLAB function
or should use all lowercase separated by underscores: e.g.
<code>my_function_name</code>
      </li>
      <li> Classes should be in <code>CamelCase</code></li>
      <li> No tabs, only two spaces per indentation level </li>
      <li> Be generous with assertions, but always identify them with strings:
      <br> e.g. <code>assert(m&lt;n && "m must be less than n");</code></li>
  </ul>

    <h2>Specific rules</h2>
    <p>
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:
    </p>
    <pre><code>
#ifndef IGL_EXAMPLE_H
#define IGL_EXAMPLE_H
...
#endif</code></pre>
  
    <p>
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.
    </p>

    <p>
Implementation should be separated from prototypes in a .cpp file.
    </p>

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

    <p>
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.
    </p>

    <h2>Useful scripts to check style</h2>
  
    <table>
      <tr>
        <th>script</th>
        <th>Description</th>
      <tr class=d0>
        <td><code>grep -L IGL_INLINE *</code></td>
        <td>Find files that aren't using "IGL_INLINE"</td>
      </tr>
      <tr class=d1>
        <td><code>grep -L "namespace igl" *</code></td>
        <td>Find files that aren't using igl namespace</td>
      </tr>
      <tr class=d0>
        <td><code>grep -P '\t' *</code></td>
        <td>Find files using [TAB] character</td>
      </tr>
      <tr class=d1>
        <td><code>grep -l "^using namespace" *.cpp</code></td>
        <td>Find .cpp files that contain ^using namespace</td>
      </tr>
      <tr class=d0>
        <td><code>grep -l 'assert([^"]*);' *</code></td>
        <td>Find files using asserts without identifier strings</td>
      </tr>
      <tr class=d1>
        <td><code>grep -l "ifndef IGL_.*[^H] *$" *</code></td>
        <td>Find .h files that contain ifndef IGL_*[^H]</td>
      </tr>
      <tr class=d0>
        <td><code>grep -L "^#ifndef IGL_" *</code></td>
        <td>Find files that don't contain #ifndef IGL_</td>
      </tr>
    </table>

    <p>See also: <a href=tutorial.html>tutorial</a>, <a
    href=doc.html>auto-documentation</a>, <a href=file-formats/index.html>file
    formats</a></p>
  </div>
  </div>
  </body>
</html>