Back to developer page.
C++ coding conventions and style guide
We try to maintain a consistent coding style because it makes reading and modifying the code easier. Our coding conventions aren't necessarily better than others (though we try to follow ones that make sense and change those that don't), but the main utility of this is consistency.
We're much stricter these days than we were, say, 10 years ago. The reason for this is that a codebase with many contributors and large size is much harder to maintain than a small one. So new code must pass tougher tests than some of the existing code. (Of course, the existing code should ideally be cleaned up more, too, but few people are motivated to work on such tasks if there are other things to do that seem more urgent.) Once code is in, it usually isn't changed for years unless we discover a bug. So we really try to put a lot of effort on making things as right as possible on the first try.
The following is not meant to be a complete description of our coding conventions. When in doubt, follow the example of the existing code.
See also the information on how and where to put ../Whitespace.
Language support
The translator should run on Python 2.7 and Python >= 3.2. The preprocessor and search code use C++11 and are allowed to use all language features supported by GCC 4.4. Since the C++11 support of this compiler version is incomplete, we refer to https://gcc.gnu.org/gcc-4.4/cxx0x_status.html for the list of implemented features.
General recommendations
We generally follow the recommendations in the book C++ Coding Standards: 101 Rules, Guidelines, and Best Practices by Herb Sutter and Andrei Alexandrescu. In the tracker or elsewhere, a mark of the form [SA x] is a reference to a rule in that book. For example, [SA 9] refers to Sutter and Alexandrescu's rule 9: "Don’t pessimize prematurely".
Comments
1 // Write complete sentences ending with periods.
2
3 // Use imperative if possible: "Return the factorial." is better than "Returns the factorial.".
4
5 // Leave a space between the slashes and the comment.
6
7 // TODO: Use this format for todo items.
8
9 /*
10 Use this style for comments spanning
11 over multiple lines and strive to write
12 self-explanatory code that doesn't need
13 comments.
14 */
15
16
17 /* For shorter multi-line comments (2-3 lines)
18 this style is also fine */
We generally prefer comments above the code (not next to it). If you really want to put a short comment next to the code, leave one space before and after the // slashes.
Subdirectories, namespaces and cmake plugins
Subdirectories:
- We don't use nested subdirectories (at least for now).
- There are two types of subdirectories:
component subdirectories correspond to a single component (e.g. one subdirectory for the PDB code, one for the landmarks code, one for the merge-and-shrink code)
grouping subdirectories group together many components that are related and too small to deserve their individual subdirectories (e.g. one for all open list variants and one for all heuristics that don't need their own subdirectory)
- Subdirectories follow the same naming conventions as filenames, methods and variables.
- Subdirectory names should be kept short.
Namespaces:
- We don't use nested namespaces (at least for now).
- Every component (= CMake plug-in) should correspond to a namespace.
- For components that have their own directory, the namespace name is derived from the directory name.
- For components that are too small for their own directory, the namespace name is derived from the main file name (or equivalently, the main class name).
- Namespaces follow the same camel-case naming convention as classes.
CMake plugins:
- There's a 1:1 correspondence between namespaces and CMake plugins.
Examples:
Component directory merge_and_shrink contains the code the merge-and-shrink component in namespace MergeAndShrink.
The file merge_and_shrink/transition_system.h would be expected to contain the class MergeAndShrink::TransitionSystem.
Grouping directory open_lists contains the code for various open list components, for example an alternation open list.
The file open_lists/alternation_open_list.h would be expected to contain the class AlternationOpenList::AlternationOpenList.
Open questions:
- We might introduce a namespace for the core code, i.e., the code that is necessary to build the planner (does not belong to any CMake plugin). Right now it is in the global namespace.
We might eventually consider settling for shorter class names and/or filenames in cases where the directory name or namespace already provide the necessary context. For example, we might say MergeAndShrink::Heuristic instead of MergeAndShrink::Heuristic; we might say AlternationOpenList::OpenList or Alternation::OpenList instead of AlternationOpenList. (If you want to argue for this, this would need further discussion.)
Header file guards
Macro names for header file guards follow this algorithm:
- Take the filename, including subdirectory name if in a subdirectory.
- Convert to uppercase.
Replace all "." and "/" with "_".
Example: learning/state_space_sample.h becomes LEARNING_STATE_SPACE_SAMPLE_H.
Guard blocks should look like this:
That's all. In particular, don't add comments to the preprocessor directives and don't add further underscores.
Includes
Order includes in the following way: header corresponding to .cc file, headers from the same directory, headers from separate directories, standard library includes. Order the includes in each group alphabetically and separate the groups by empty lines. Add another empty line before any using namespace declarations. Use two empty lines to separate includes or using namespace declarations from the remaining code. Here is a contrived example:
1 #include "pattern_generation_edelkamp.h"
2
3 #include "zero_one_pdbs_heuristic.h"
4
5 #include "../causal_graph.h"
6 #include "../timer.h"
7
8 #include "../ext/tree.hh"
9
10 #include <algorithm>
11 #include <cassert>
12 #include <vector>
13
14 using namespace std;
15
16
17 PatternGenerationEdelkamp::PatternGenerationEdelkamp(const Options &opts)
18 ...
Constructors, destructors and assignment operators
- Add default destructor only for base classes (i.e., if other classes derive from them). The destructor should of course be virtual.
Explicitly remove copy constructor, i.e., declare it as = delete. TODO: Do we explicitly allow exceptions to this rule (e.g. for FactPair, DynamicBitset)?
Function signatures
Use const methods whenever appropriate.
Pass strings by const reference.
When overriding a virtual method, mention virtual again in the declaration and mark it as override (i.e., virtual int foo() override; rather than int foo();).
Anti-idioms
Don't write NULL or 0 for null pointers. Use nullptr.
Don't write (ptr != nullptr). Write (ptr).
Don't write (ptr == nullptr). Write (!ptr).
Don't write (seq.size() == 0). Write (seq.empty()).
Don't write (seq.size() != 0). Write (!seq.empty()).
- Don't append underscores to constructor variables. Use the same name as the member variable (preferrable) or a different name.
Passing and storing tasks
Pass "const shared_ptr<AbstractTask> &" if callee stores task.
Pass "const TaskProxy &" if callee doesn't store task.
Don't store TaskProxy as member variable, instead add private/protected method that retrieves the required proxy class (e.g. TaskProxy, OperatorsProxy, VariablesProxy, etc.) from the AbstractTask.