forked from libigl/libigl
-
Notifications
You must be signed in to change notification settings - Fork 0
/
style_guidelines.html
212 lines (194 loc) · 6.69 KB
/
style_guidelines.html
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
<!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 <[email protected]>
//
// 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 <[email protected]>
//
// 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>