Code documentation
- A design document must match what is written in code. One can have a sketch document before writing code for sake of direction but in many cases the design is known to change as refactoring take its course. The design document must be updated during and after developement.
- Every piece of code must have well written comments and they must be kept up to date. Code that isn't worth commenting probably isn't worth executing either.If a crucial piece of information is documented elsewhere, or if two or more files need to be maintained in sync, then that should be mentioned in the code (in both places...).
- It's much more important to document why a method exists than what it does. Start with why you are writing it rather explaining what it does.
- Never use a debugger to understand the programming logic in your own code. First the documentation must make it clear what a piece of code does and the code must be clean enough to expose logic.
- Avoid vacuous statements, they are insulting. Documentation must have meaning and reason.
- Do not write too much documentation, noone will read it let alone update it.
