Documentation

(More TBD)

Documentation is good.

• This will help others understand what you are doing.
• This will help you think formally about what you are doing and come up with a better design.
• This will help your code stand the test of time and not get removed by an angry person not understanding what you did who is refactoring the code base two years later.

We expect the code base to be well documented with three types of documentation, detailed below.

Doxygen Docs

(More TBD)

We require all public APIs to be documented with doxygen. Doxygen comments should be javadoc style, with descriptive comments describing the code behavior and contracts, at the top of each public function, class and method. Doxygen comments should not include implementation details, but rather establishes behavioral contracts, with the exception of performance (it is okay to mention that something can be slow, even if it being slow is an implementation detail that can change). This will be enforced automatically on our CI builds.

(TODO: describe the checks on Travis here)

Inline Documentation

(More TBD)

Inline documentation should be provided in these places:

• At the beginning of private functions, members or inner classes, unless they are short and self-documenting.
• At the beginning of each test case, describing what the test case does.
• At the beginning of large, dense code blocks, providing a high level overview of the code.
• Wherever the code is not "obviously correct", explaining the logic to improve readability.

Design Docs

(More TBD)

• Go to our design doc repo
• Fork the repo and follow the instruction to write your design doc
• Submit a PR and assign reviewers. We want it to be a discussion!
• You can do this before you start writing your code or after. Doing this before allows you to get input from other people earlier, but you might need to come back and change things so they are up-to-date.
• When in doubt, just write it down. (whether you need a design doc, whether something needs to go into the design doc, etc. )