Skip to content

Coding Guidelines

Jump to bottom
Jeff Delaune edited this page Oct 20, 2020 · 2 revisions

This page provides resources and guidance to start contributing code efficiently to the X framework.

Not all parts of the code follow these guideline equally, especially in the older classes. This is an on-going effort from all developers. Please do your best to follow them for any new code that you write, so we don't need massive cleanups in the future.

C++

The X framework attempts to follow two sets of C++ guidelines:

  1. ISO C++ Core Guidelines

  2. Google C++ style guide

Even though there is an effort to merge the Google guidelines into the ISO ones, they are complementary. The ISO guidelines aim at promoting the use of the ISO C++ standard, while the Google ones place the emphasis on the style. The ISO guidelines make the effort the provide to discuss the reason behind each guideline, so you can decide if it applies to your problem.

Documentation

Comments

Code should be commented as exhaustively as possibly. That includes:

  • local comments: what is the logic of the code inside a function?
  • prototype comments: what is this function is doing? What are the inputs / outputs?
  • class comments: what is this class doing? What are its data members?

For local comments, be exhaustive but don't comment the obvious. A rule of thumb is that someone should be able to read only the comments and understand what the code is doing at high level.

For comment format, the X framework follows the Doxygen Doxygen guidelines format, since these allows the generation a full PDF documentation.

Branching

The X framework follows this branching model. Here are a few key points:

  • Every new software feature is developed on a separate branch.
  • 'devel' is the default development branch any developer should fork from.
  • Once a feature is developed, the developed issues a merge request to 'devel'.
  • Only maintainers can merge feature branches in devel.
  • You become maintainer of a repo once you have convinced other maintainers you know the repo enough.
  • 'master' is the release branch.
  • 'devel' is merged into 'master' for each "production" release (e.g. paper, project milestone).
Clone this wiki locally