/* 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.
if (some_function("moo", 2))
// this needs some explanation
while (end != do_other_stuff(foo) || ! foo)
\section CodingStandardsSwitches Switches
You'll sometimes see code like this:
throw InternalError(PALUDIS_HERE, "Unexpected value for my_enum");
} while (false);
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:
for (MyType::Iterator i(my_container.begin()), i_end(my_container.end()) ;
i != i_end ; ++i)
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 126.96.36.199.
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
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
Don't use <code>vector<bool></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.