Code Comments

Code is not only for the computer, but it should be readable for humans, too. Up-to-date code comments are essential to make code understandable for others. Thus please use following techniques (in order of preference):

1. Comment interfaces following design-by-contract.
2. You should also add assertions to state what should be true at a specific position in the code. Advantage: Syntax is checked and they are automatically verified at run-time. So they are not only useful for people reading the code but also for tools. Note: Do not use assert for user-APIs, always handle arguments of user-APIs like untrusted input.
3. If the "comment" might be useful to be printed during execution, use logging.
4. Otherwise comment within source. Use TODO to indicate that something is not yet done. Before merging, relevant TODOs should be fixed or create a left-over issue