aboutsummaryrefslogtreecommitdiff
path: root/0.4.0/doc/doc_coding_standards.doxygen
diff options
context:
space:
mode:
Diffstat (limited to '0.4.0/doc/doc_coding_standards.doxygen')
-rw-r--r--0.4.0/doc/doc_coding_standards.doxygen184
1 files changed, 184 insertions, 0 deletions
diff --git a/0.4.0/doc/doc_coding_standards.doxygen b/0.4.0/doc/doc_coding_standards.doxygen
new file mode 100644
index 0000000..5003023
--- /dev/null
+++ b/0.4.0/doc/doc_coding_standards.doxygen
@@ -0,0 +1,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.
+
+*/