Documentation

Formal documentation

To be useful documentation should include a readable description of what the code is supposed to do (Requirements), how it works (Design), which functions it depends on and how it is used by other code (Interfaces), and how it is tested. For extra credit, the documentation can include a discussion of alternative solutions and suggestions for extensions or maintenance.

Dick Brandon: “Documentation is like sex; when it's good, it's very, very good, and when it's bad, it's better than nothing.”

Consider writing the documentation first

Some programmers believe that the best approach is “Code first and answer questions later.” Through experience most of us learn that developing a design and then implementing it leads to a much more satisfactory result.

Development projects are almost never completed on schedule. If documentation and testing are left for last, they will get cut short. Writing the documentation first assures that it gets done and will probably reduce development time.