/
CODING_STANDARDS.txt
112 lines (78 loc) · 3.35 KB
/
CODING_STANDARDS.txt
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
This is a general list of coding style standards to use when adding or modifying
code in Fabber. Adhering to these standards will improve code readability
because you can make assumptions about the code without having to check
(e.g. the symbol mvn_dist is a local variable, not a class, function or
a member variable). In addition, keeping style consistent ensures that
version control diffs show only meaningful changes and not irrelevant
changes to spacing, etc.
Updating Fabber to these guidelines is an ongoing task as files are edited
and refactored. Currently many files are not updated. rundata.cc/rundata.h are
believed to be reasonably consistent with these guidelines.
Guidelines will be added as required, but the intention is to keep this as
brief as possible and not turn into a 'How you should write C++' guide.
1. Bracing/indent style
BSD/Allman style is used, e.g.
void FabberRunData::Parse(int argc, char** argv)
{
for (int a = 1; a < argc; a++)
{
if (string(argv[a], 0, 2) == "--")
{
string key = argv[a] + 2; // skip the "--"
AddKeyEqualsValue(key);
}
else
{
LOG << "Option doesn't begin with --: " + string(argv[a]);
throw Invalid_option("An option doesn't begin with --\n");
}
}
}
This tends to separate out the code and make it less dense. A major issue
with Fabber code at present is that too much is crammed into a single function!
Use of this style will emphasise this and encourage refactoring (hopefully).
Eclipse contains this style as a built in option. Once selected, SHIFT-CTRL-F will
reformat your current file in this style. The only difference from the Eclipse
default is that lines up to 120 characters long are allowed - Eclipse wraps at
80 characters which seems anachronistic.
A .clang-format file is also provided which can be used with the clang-reformat
formatter. Some editors can use this, e.g. Visual Studio Code (note this is not
the same as Visual Studio!)
2. Tabs/spaces
Spaces are used for all indentation. Tabs in existing files are converted to 4 spaces.
Ideally tabs are better but in practice tend to cause problems when they are interpreted
differently by different editors.
3. Naming conventions
Classes are in CamelCase, e.g.
FabberRunData
FwdModel
Functions are also in CamelCase, e.g.
FwdMode.Evaluate
Variables are in lower case with underscores, e.g.
image_priors
Member variables should be prefixed with m_, e.g.
m_param_names[3]
4. Header files
Header files should be self-contained. I should always be able to do:
#include "fwdmodel.h"
Without having to worry about including any other headers. This means
that fwdmodel.h should contain all #includes that it needs.
Header files should include guards against multiple inclusion, e.g.
#ifndef FABBER_FWDMODEL_H
#define FABBER_FWDMODEL_H
...
...
#endif
or
#pragma once
Header files should not normally contain function implementations.
As a general rule, only empty functions or one-line functions (e.g.
getters/setters) should be implemented in a header file.
Never put "using namespace" in a header file, as it will affect
any code which includes that header.
5. Documentation and comments
All public and protected members should have Doxygen documentation
// Comments should be used to explain code in cc files
Do not 'comment out' code. Either
- Remove it (Version control means it isn't really lost)
- Use #ifdef 0 ... #endif to temporarily remove