aboutsummaryrefslogtreecommitdiff
path: root/0.8.0/doc/doc_coding_standards.doxygen
blob: 50030231cd0c90112510ad490d9ed57ec08ecb94 (plain)
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
/* vim: set ft=cpp tw=80 sw=4 et : */

/**
\page CodingStandards Coding Standards

These are rough guidelines. You should stick to these unless there's a good
reason to do otherwise. There are lots more standards that aren't documented
here yet -- ask for clarification as necessary.

\section CodingStandardsCopyrights Copyrights and Licence

Paludis is licenced under the GPLv2. Any contributions must use this licence.
You should copy the standard licence header from another source file when
creating new source files.

Copyright is handled on a per-file basis. If you are the primary author of
a file, you should list yourself as the copyright holder. If you make a
substantial contribution to a source file (for example, one or more
non-trivial classes, functions or methods), you should add yourself as a
copyright holder on that file. You should <em>not</em> add to the copyright for
small changes or bug fixes.

Copyright years are per contributor. See, for example, paludis/fs_entry.hh for
a file that has multiple copyright holders with different years.

Substantial contributors should also list themselves in the AUTHORS file.

\section CodingStandardsIndentingAndSpacing Indenting and Spacing

Indents are four spaces. There are no tabs anywhere. Braces go on a line of
their own, and may be omitted if the clarity of the code isn't affected. Make
sure you don't include trailing whitespace.

Function calls have no space before or after the parentheses. Most operators
and built-in functions have spaces before the opening parenthesis but not
inside. The ! operator has a space after it.

For example::
\code
if (some_function("moo", 2))
    do_stuff("moo");
else
{
    // this needs some explanation
    while (end != do_other_stuff(foo) || ! foo)
        ++foo;
}
\endcode

\section CodingStandardsSwitches Switches

You'll sometimes see code like this:

\code
do
{
    switch (my_enum)
    {
        case e_one:
            // ...
            continue;

        case e_two:
            // ...
            continue;
    }

    throw InternalError(PALUDIS_HERE, "Unexpected value for my_enum");
} while (false);
\endcode

The reason for using this rather than a <code>default:</code> label is that the
compiler will (or at least the compiler we use will) generate a warning if
someone later goes and adds <code>e_three</code>, and we haven't updated our
switch to recognise it.

\section CodingStandardsComments Comments

All public and protected interfaces and classes should be documented in the
header files via Doxygen. Implementations should be documented appropriately --
explain complicated or unobvious parts and anything that can easily be broken
by other people. Don't bother with comments on obvious things.

\section CodingStandardsNaming Naming

Types are named in <code>MixedCaseNoUnderscores</code>.

Variables and functions are named in <code>lower_case_with_underscores</code>.

Private member variables that aren't going to end up being used anywhere
external are <code>_prefixed_with_underscore</code>.

Template values are <code>suffixed_with_underscore_</code>, and template
typenames are <code>SuffixedAsWell_</code> (and use <code>typename</code> rather
than <code>class</code>, \ref EffCpp item 42).

The files for <code>SomeClass</code> (and any small related utilities) would be
<code>some_class.hh</code> and <code>some_class.cc</code>. We are somewhat
inconsistent when it comes to what warrants its own file -- originally it was
pretty much one class per file, but then compiles started taking too long so
it's now more like one class plus related utilities and exceptions per file.

Macros are <code>PALUDIS_UPPER_CASE</code>, but they're evil (\ref TCppPL
section 7.8, \ref EffCpp item 2) so don't use them.

Very short names for loop indices and the like are fine, but prefer longer,
self-documenting names for proper variables. For loop iterator pairs, the
usual style is:

\code
for (MyType::Iterator i(my_container.begin()), i_end(my_container.end()) ;
        i != i_end ; ++i)
{
    // ...
}
\endcode

If there's a convenient standard library algorithm available, use that
instead of a manual loop (\ref EffSTL item 43).

\section CodingStandardsPointers Pointers and References

Try to avoid returning raw pointer types from raw interfaces, especially if the
programmer is expected to deallocate them manually. Make liberal use of
<code>paludis::CountedPtr</code> instead -- it's low overhead and a lot less
prone to subtle screwups. See \ref EffCpp item 18.

Pass object parameters by const reference rather than pointer to const unless
you're prepared to accept a zero pointer. Avoid pass by value except for small
integral types. See \ref EffCpp item 20.

\section CodingStandardsNamespaces Namespaces

Everything under <code>paludis/</code> should be inside namespace
<code>paludis</code>. Sometimes sub-namespaces are used where they look useful.

\section CodingStandardsIncludeGuards Include Guards

Include guards are <code>\#define PALUDIS_GUARD_FILE_NAME_HH 1</code>.

\section CodingStandardsStandardLibrary Standard Library

Never use <code>using namespace std</code>. It can bring arbitrary weirdness
into the current namespace. It's ok to selectively introduce things from std
where they're used a lot. See \ref TCppPL section 8.2.9.1.

Make use of the standard library where suitable. It has fewer bugs than
code you write yourself, and it may be doing clever optimisations behind
the scenes.

Remember the container member functions. Many containers have template
constructors that take iterator pairs. Many containers have assign and
swap methods. Use these over <code>std::copy</code>. See \ref EffSTL item
25.

Don't use <code>vector&lt;bool&gt;</code>. It's just not worth it. See
\ref EffSTL item 18.

Although some compilers will let you get away with <code>std::make_pair("foo",
"bar")</code>, some won't. Strictly speaking this violates the standard.
Use <code>std::make_pair(std::string("foo"), std::string("bar"))</code> instead.

\section CodingStandardsCasts Casts

<code>dynamic_cast</code> is banned. It's slow (\ref EffCpp item 27) and a sign
that you should be using one of visitors (\ref GoF Visitor), multiple dispatch
(\ref MCppD chapter 11) or capability queries via a <code>get_interface</code>
type method (for example, as described in \ref GoF Composite -- Implementation
item 4) instead.

<code>reinterpret_cast</code> is probably banned as well, unless we end up
having to talk to some weirdly broken C libraries.

There are very few legitimate uses for <code>const_cast</code>. It
<em>might</em> be ok to use it as described in \ref EffCpp item 3. It
<em>might</em> be ok to use it to talk to C libraries.

There's nothing wrong with making appropriate use of <code>static_cast</code>.

Old C style <code>(Type) variable</code> casts are banned. Function style casts
(that is, <code>Type(value)</code>) should only be used when calling an explicit
constructor to pass an object to a function. See \ref EffCpp item 27.

*/