Differences between revisions 10 and 57 (spanning 47 versions)
Revision 10 as of 2010-10-31 16:52:56
Size: 3843
Editor: MalteHelmert
Comment:
Revision 57 as of 2021-07-02 15:02:48
Size: 2080
Comment:
Deletions are marked like this. Additions are marked like this.
Line 3: Line 3:
= Coding conventions = = Information for developers =
Line 5: Line 5:
== Mercurial == Subpages:
Line 7: Line 7:
=== Workflow ===  * [[/Requirements]]: the set of rules regarding which versions of operating systems, compilers etc. we support
 * [[/DevelopmentSetup]]: which tools to install for working on the planner
 * [[/AddingSourceFiles]]: how to add new source files to the planner
 * [[/Git]]: our Git workflow and Git tips and tricks
 * [[/CodingConventions]]: coding conventions for C++ code
 * [[/Whitespace]]: how to indent, where to break lines, where to put spaces etc. in C++ code
 * [[/Uncrustify]]: using the {{{uncrustify}}} source code pretty printer
 * [[/Includes]]: using {{{include-what-you-use}}} to find missing/redundant includes and forward declarations
 * [[/CodeReview]]: how to use Github pull requests for code reviews
 * [[/GithubActions]]: information on Github actions
 * [[/ImplementationDetails]]: more in-depth descriptions on how some classes are implemented
 * [[/CodeBasesToMerge]]: code from papers we want to merge in the (medium-term) future
 * [[/ReviewQueue]]: Malte's FIFO list of issues to review
 * [[/LongTermPlans]]: long-term wishlist of changes with broader scope
 * [[/ProblemTransformations]]: problem transformations performed by the planner that might trip up users interested in non-classical planning
 * [[/CmakeTipsAndTricks]]: tips and tricks for CMake
 * [[/Profiling]]: on using valgrind and friends
 * [[/ReleaseWorkflow]]: how to create a release version
 * [[/ChangelogFormat]]: description of the changelog format
 * [[/Sprint]]: information, statistics, and news about our Fast Downward sprints
 * [[/Blog]]: articles describing parts of the code base
Line 9: Line 29:
We follow the [[http://mercurial.aragost.com/kick-start/tasks.html|task-based workflow explained here]]. All significant development should be in response to an issue in the [[http://issues.fast-downward.org/|tracker]], let's say issue1000. Then the usual development process involves two roles, "developer" and "reviewer" (usually Malte), and works as follows: == Other bits and pieces ==
Line 11: Line 31:
 1. Developer creates a new branch issue1000 in their own repository, usually branching off the newest revision in default. '''Note''' the exact spelling of the branch. Being consistent here allows us to automate some of these steps in the future.
 1. Developer resolves the issue in the branch. (Developer '''does not''' close the branch or push the changes to the master repository.)
 1. Developer sets the status of the issue to "reviewing".
 1. Reviewer pulls the issue1000 branch into their own repository.
 1. Reviewer reviews the code.
    * If reviewer is not satisfied, go back to step 2.
    * If reviewer is satisfied:
      1. Reviewer closes the issue1000 branch.
      1. Reviewer merges the issue1000 branch into the default branch.
      1. Reviewer pushes the issue1000 branch and its merge into the master repository.
 
=== Commit messages ===

The first line of the commit message should consist of a self-contained summary and be no longer than 67 characters.

All other lines should be below 80 characters.

== Python code ==

We follow [[http://www.python.org/dev/peps/pep-0008/|PEP 8]].

== C++ code ==

This is not meant to be a complete description of our coding conventions.
When in doubt, follow the example of the existing code.

To keep the size of this file reasonable, the following parts have been broken out to subpages:

 * [[/C++Formatting]]: line length, how to break lines, where to put spaces, etc.

=== General recommendations ===

We generally follow the recommendations in the book
[[http://www.gotw.ca/publications/c++cs.htm|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".

=== Namespaces ===

 * Every subdirectory should correspond to a namespace.
 * Avoid nested namespaces or subdirectories of subdirectories.
 * Namespaces follow the same camel-case naming convention as classes, while directory names follow the naming conventions for methods and variables. For example, file {{{my_subdir/my_class.h}}} would be expected to contain a definition of class {{{MySubdir::MyClass}}}.
 * Namespaces should have short, single-word names if possible. (The previous example only uses an underscore in the subdirectory name for sake of illustration.)

=== 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:
{{{#!cplusplus
#ifndef LEARNING_STATE_SPACE_SAMPLE_H
#define LEARNING_STATE_SPACE_SAMPLE_H
// ...
#endif
}}}

That's all. In particular, don't add comments to the preprocessor directives and don't add further underscores.

=== Function signatures ===

 * Use {{{const}}} methods whenever appropriate.
 * Pass {{{string}}}s by const reference.
 * When overriding a virtual method, mention {{{virtual}}} again in the declaration (i.e., {{{virtual int foo();}}} rather than {{{int foo();}}}).
 * '''Mailing lists:''' Core developers, please subscribe to both the public and the internal mailing lists mentioned on the HomePage.
 * '''Admin interface to the internal mailing list:''' https://www.maillist.unibas.ch/mailman/options/downward-dev/
 * '''Python code:''' We follow [[http://www.python.org/dev/peps/pep-0008/|PEP 8]] and support Python >= 3.6.

Back to the HomePage.

Information for developers

Subpages:

Other bits and pieces

FastDownward: ForDevelopers (last edited 2024-03-15 12:14:37 by MalteHelmert)