202304281434-writing_code_documentation

Goals: clarify complex parts of code, making your program easier to navigate, and explain how and why different parts of your program are used.

Depending on the goal, you can document on different levels:

  • Inline strings on line level
  • Docstrings on module and function level
  • Project documentation on project level

Inline comments

Comments can guide readers in understand complex parts of code, but some programmers will argue that if you have to rely on comments, your code is not clear enough. That's an ongoing debate and I'd say you need to decide this on a case by case basis. Personally, I'd add a short comment to complex parts, because it never hurts.

What code cannot convey however is the history and context of a certain piece of code. Sometimes coding decisions have to be made because of external circumstances or because you contribute to an older software product where you cannot avoid dealing with some side-effects of other parts of the software. Or perhaps the value of some variable is informed by business decisions. In this case, inline comments can provide contextual information to the person having to understand your code.

Docstrings

In Python, use triple "double" quotes, either in a one-line or multi-line docstring.

Links:

Project documentation

Commonly a project requires at least a README file containing:

  • What does the software do?
  • What are the dependencies?
  • Provide understandable instructions on how to use the software.