Documentation Guidelines

This guideline describes best practices for code documentation in Polypheny.

Language

The documentation must be written in English. Please write in simple and concise sentences (it is not a poem).

What to document

You shouldn’t document what the code is doing, but you should document why it’s doing it.

The purpose of code documentation is to allow other programmers to understand quickly what an element in the code is doing. If the purpose of piece of code is not obvious comment why it is required. The why is often more important than the how!

Do not comment the obvious

Do not write comments about obvious things. Remember that the documentation has to be maintained as well.

Write better code

Self-explanatory code is always the better documentation! Therefore, if a comment can be avoided by renaming and/or refactoring the code, this is always the preferred approach.

Nevertheless, this is should not be seen as an excuse for writing no comments. While, meaningful names can avoid many comments on how things are working, there are constructs which are obscure by its own nature (DateTime formatters, RegExp, …). Furthermore, also meaningful names do often not express the purpose of the code.