← Back to branch summary

~ubuntu-branches/ubuntu/natty/dolfin/natty

« back to all changes in this revision

Viewing changes to doc/manual/chapters/codingstyle.tex

  • Committer: Bazaar Package Importer
  • Author(s): Johannes Ring
  • Date: 2011-02-24 10:34:44 UTC
  • mfrom: (1.1.7 upstream) (14.1.4 sid)
  • Revision ID: james.westby@ubuntu.com-20110224103444-n3fwnmh32lfoske0
Tags: 0.9.10-1
http://bugs.debian.org/612602
* New upstream release. This release fixes bug "FTBFS: error:
  'SCOTCH_Dgraph' was not declared in this scope" (closes: #612602).
* debian/control:
  - Add libslepc3.1-dev and libboost-thread-dev to Build-Depends and
    Depends field in binary package libdolfin0-dev.
  - Bump build dependency on python-ufc to >= 2.0.0.
  - Remove Build-Depends-Indep field as upstream no longer ships the
    user manual.
  - Remove old fields Conflicts, Provides, and Replaces from
    libdolfin0-dev, libdolfin0, libdolfin0-dbg, and python-dolfin.
* Remove all patches as they are now incorporated upstream.
* Add dolfin-plot and dolfin-version to debian/dolfin-bin.install.
* Remove .doc-base file since the user manual is removed by upstream.
* Remove targets clean and install/dolfin-doc from debian/rules since
  they are no longer needed.

Show diffs side-by-side

added added

removed removed

Lines of Context:
doc/manual/chapters/codingstyle.tex
1
 
\chapter{Coding style}
2
 
\label{sec:codingstyle}
3
 
\index{coding style}
4
 
 
5
 
To streamline the \dolfin{} source code and ease the job for
6
 
maintainers that need to read and edit large amounts of code,
7
 
developers should try to follow the below coding style when submitting
8
 
patches to \dolfin{}.
9
 
 
10
 
The guideline below is for C++ but may in some cases be extrapolated
11
 
to Python.
12
 
 
13
 
\section{Naming conventions}
14
 
 
15
 
\subsection{Class names}
16
 
 
17
 
Use camel caps for class names:
18
 
\begin{code}
19
 
class FooBar
20
 
{
21
 
  ...
22
 
};
23
 
\end{code}
24
 
 
25
 
\subsection{Function names}
26
 
 
27
 
Use lower-case for function names and underscore to separate words:
28
 
\begin{code}
29
 
void foo();
30
 
void bar();
31
 
void foo_bar(...);
32
 
\end{code}
33
 
 
34
 
Functions returning a value should be given the name of that value,
35
 
for example:
36
 
\begin{code}
37
 
class Array:
38
 
{
39
 
public:
40
 
 
41
 
  /// Return size of array (number of entries)
42
 
  uint size() const;
43
 
 
44
 
};
45
 
\end{code}
46
 
 
47
 
In the above example, the function should be named \texttt{size} rather
48
 
than \texttt{get\_size}. On the other hand, a function not returning a
49
 
value but rather taking a variable (by reference) and assigning a value
50
 
to it, should use the \texttt{get\_foo} naming scheme, for example:
51
 
\begin{code}
52
 
class Parameters:
53
 
{
54
 
public:
55
 
 
56
 
  /// Retrieve all parameter keys
57
 
  void get_parameter_keys(std::vector<std::string>& parameter_keys) const;
58
 
 
59
 
};
60
 
\end{code}
61
 
 
62
 
\subsection{Variable names}
63
 
 
64
 
Use lower-case for variable names and underscore to separate words:
65
 
\begin{code}
66
 
Foo foo;
67
 
Bar bar;
68
 
FooBar foo_bar;
69
 
\end{code}
70
 
 
71
 
\subsection{Enum variables and constants}
72
 
 
73
 
Enum variables should be lower-case with underscore to separate words:
74
 
\begin{code}
75
 
enum Type {foo, bar, foo_bar};
76
 
\end{code}
77
 
 
78
 
We try to avoid using \texttt{\#define} to define constants, but when
79
 
necessary constants should be capitalized:
80
 
\begin{code}
81
 
#define FOO 3.14159265358979
82
 
\end{code}
83
 
 
84
 
\subsection{File names}
85
 
 
86
 
Use camel caps for file names if they contain the
87
 
declaration/definition of a class. Header files should have the
88
 
suffix~\texttt{.h} and implementation files should have the
89
 
suffix~\texttt{.cpp}:
90
 
\begin{code}
91
 
FooBar.h
92
 
FooBar.cpp
93
 
\end{code}
94
 
 
95
 
Use lower-case for file names that contain utilities/functions (not
96
 
classes).
97
 
 
98
 
\section{Miscellaneous}
99
 
 
100
 
\subsection{Comments}
101
 
 
102
 
Comment your code, and do it often. Capitalize the first letter and
103
 
don't use punctuation (unless the comment runs over several
104
 
sentences). Here's a good example from \texttt{TopologyComputation.cpp}:
105
 
\begin{code}
106
 
// Check if connectivity has already been computed
107
 
if (connectivity.size() > 0)
108
 
  return;
109
 
 
110
 
// Invalidate ordering
111
 
mesh._ordered = false;
112
 
 
113
 
// Compute entities if they don't exist
114
 
if (topology.size(d0) == 0)
115
 
  computeEntities(mesh, d0);
116
 
if (topology.size(d1) == 0)
117
 
  computeEntities(mesh, d1);
118
 
 
119
 
// Check if connectivity still needs to be computed
120
 
if (connectivity.size() > 0)
121
 
  return;
122
 
 
123
 
...
124
 
\end{code}
125
 
 
126
 
\subsection{Integers and reals}
127
 
 
128
 
Use \texttt{dolfin::uint} instead of \texttt{int} (unless you really
129
 
want to use negative integers which is rare) and \texttt{dolfin::real}
130
 
instead of \texttt{double}:
131
 
\begin{code}
132
 
uint i = 0;
133
 
double x = 0.0;
134
 
\end{code}
135
 
These are typedefs for the standard C++ types \texttt{unsigned int}
136
 
and \texttt{double} (defined in \texttt{dolfin/common/types.h}).
137
 
 
138
 
\subsection{Placement of brackets}
139
 
 
140
 
Curly brackets following a control statement should appear in the next
141
 
line and not be indented:
142
 
\begin{code}
143
 
for (uint i = 0; i < 10; i++)
144
 
{
145
 
  ...
146
 
}
147
 
\end{code}
148
 
 
149
 
\subsection{Indentation}
150
 
 
151
 
Indentation should be two spaces and it should be spaces, \emph{not}
152
 
tab(s).
153
 
 
154
 
\subsection{Header file layout}
155
 
 
156
 
Header files should follow the below template:
157
 
\vspace{-0.5cm}
158
 
\begin{code}
159
 
// Copyright (C) 2008 Foo Bar.
160
 
// Licensed under the GNU LGPL Version 2.1.
161
 
//
162
 
// Modified by Bar Foo, 2008.
163
 
//
164
 
// First added:  2008-01-01
165
 
// Last changed: 2008-02-01
166
 
 
167
 
#ifndef __FOO_H
168
 
#define __FOO_H
169
 
 
170
 
namespace dolfin
171
 
{
172
 
 
173
 
  class Bar; // Forward declarations here
174
 
 
175
 
  /// Documentation of class
176
 
 
177
 
  class Foo
178
 
  {
179
 
  public:
180
 
 
181
 
    ...
182
 
 
183
 
  private:
184
 
 
185
 
    ...
186
 
 
187
 
  };
188
 
 
189
 
}
190
 
 
191
 
#endif
192
 
\end{code}
193
 
 
194
 
\subsection{Implementation file layout}
195
 
 
196
 
Implementation files should follow the below template:
197
 
\begin{code}
198
 
// Copyright (C) 2008 Foo Bar.
199
 
// Licensed under the GNU LGPL Version 2.1.
200
 
//
201
 
// Modified by Bar Foo, 2008.
202
 
//
203
 
// First added:  2008-01-01
204
 
// Last changed: 2008-02-01
205
 
 
206
 
#include <dolfin/Foo.h>
207
 
 
208
 
using namespace dolfin;
209
 
 
210
 
//-----------------------------------------------------------
211
 
Foo::Foo() : // variable initialization here
212
 
{
213
 
  ...
214
 
}
215
 
//-----------------------------------------------------------
216
 
Foo::~Foo()
217
 
{
218
 
  // Do nothing
219
 
}
220
 
//-----------------------------------------------------------
221
 
\end{code}
222
 
 
223
 
The horizontal lines above should be exactly~79 characters
224
 
wide but have been shortened here to fit the page.
225
 
 
226
 
\subsection{Including header files}
227
 
 
228
 
Don't use \texttt{\#include <dolfin.h>} or \texttt{\#include
229
 
  <dolfin/dolfin\_foo.h>} inside the DOLFIN kernel. Only include the
230
 
portions of DOLFIN you are actually using.
231
 
 
232
 
\subsection{Forward declarations}
233
 
 
234
 
Actually, try to include as little as possible and use forward
235
 
declarations whenever possible (in header files). Put the
236
 
\texttt{\#include} in the implementation file.
237
 
 
238
 
\subsection{Explicit constructors}
239
 
 
240
 
Make all constructors (except copy constructors) explicit if there is no particular
241
 
reason not to do so:
242
 
\begin{code}
243
 
class Foo
244
 
{
245
 
  explicit Foo(uint i);
246
 
};
247
 
\end{code}
248
 
 
249
 
\subsection{Virtual functions}
250
 
 
251
 
Always declare inherited virtual functions as virtual in the subclasses. This makes it
252
 
easier to spot which functions are virtual.
253
 
 
254
 
\begin{code}
255
 
class Foo
256
 
{
257
 
  virtual void foo();
258
 
  virtual void bar() = 0;
259
 
};
260
 
 
261
 
class Bar
262
 
{
263
 
  virtual void foo();
264
 
  virtual void bar();
265
 
};
266
 
\end{code}
267
 
 
268
 
\section{Use of libraries}
269
 
 
270
 
\subsection{Prefer C++ strings and streams to old C-style \texttt{char*}}
271
 
 
272
 
Use std::string instead of \texttt{const char*} and use std::istream and
273
 
std::ostream instead of \texttt{FILE}. Avoid \texttt{printf},
274
 
\texttt{sprintf} and the like.
275
 
 
276
 
There are exceptions to this rule where we need to use old C-style
277
 
function calls. One such exception is handling of command-line
278
 
arguments (\texttt{char* argv[]}).