This page is still under construction
This page contains a collection of suggestions for what to think about when writing code-level documentation. The documentation in code falls into two categories:
- Implementation documentation: these comments are intended to help developers understand how code works, in places where this isn't immediately obvious from the code itself. This form of documentation is useful, but it is not the most important reason for documentation, and most documentation does not fit this category.
- It supports abstraction. This is the most important reason for documentation, and what you should be thinking about when writing documentation. The goal of abstraction is to create reusable modules with simple interfaces that hide complex internals; it should be much easier to use a module than to understand its implementation. The module's documentation describes its interface.
- Documentation should not repeat what is obvious from the code