|
@@ -1,212 +0,0 @@
|
|
|
-<!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>
|
|
|
|
|
-// 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
|
|
|
|
|
- </code></pre>
|
|
|
|
|
- <h3>example_fun.cpp</h3>
|
|
|
|
|
- <pre><code>
|
|
|
|
|
-// 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
|
|
|
|
|
- </code></pre>
|
|
|
|
|
-
|
|
|
|
|
-
|
|
|
|
|
-
|
|
|
|
|
- <h2 id=general_rules>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>
|
|
|
|
|
-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 <code>const</code>.</li>
|
|
|
|
|
- <li>
|
|
|
|
|
-Use C++ references (e.g. <code>Matrix & mat</code>) for inputs and outputs
|
|
|
|
|
-rather than pointers (e.g. <code>Matrix * mat</code>) or pass-by-copy (e.g.
|
|
|
|
|
-<code>Matrix mat</code>).
|
|
|
|
|
- </li>
|
|
|
|
|
- <li>
|
|
|
|
|
-Write multiple prototypes if you'd like to have optional parameters with
|
|
|
|
|
-default values.
|
|
|
|
|
- </li>
|
|
|
|
|
- <li>
|
|
|
|
|
-External dependencies (besides Eigen and OpenGL) are only allowed within extras.
|
|
|
|
|
- </li>
|
|
|
|
|
- <li>
|
|
|
|
|
-New extras and their dependencies must be discussed first.
|
|
|
|
|
- </li>
|
|
|
|
|
- <li>
|
|
|
|
|
-Hard-to-compile or obscure external dependencies can go in the <code>external/</code> directory.
|
|
|
|
|
- </li>
|
|
|
|
|
- <li>
|
|
|
|
|
-Do not use the <code>using namespace</code> 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 and always identify them with strings:
|
|
|
|
|
- <br> e.g. <code>assert(m<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 -lP '\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] *$" *.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>
|
|
|
|
|
- <tr class=d1>
|
|
|
|
|
- <td><code>grep -L "^// This file is part of libigl" *</code></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>
|
|
|
Alec Jacobson