Programs don't document themselves. However, because the readership of the code itself is both self-selecting and restricted it is the most common form of documentation to be overlooked. Programmers believe that if their code works it should never need a second glance. Enhancements, maintenance, and bug fixing are all part and parcel of the process, so you need to document code to ensure its long life span. As a rule of thumb, document the code as you go and make sure your code is covered with enough helpful comments that a newcomer could read through them and together with the code itself work out what is going on. Most programmers include these only as an aid for themselves at particularly hairy parts of the program. If there are genuinely convoluted programming aspects these should be documented separately in an accompanying document. For large projects separate, full-scale documentation is mandatory. If this is changing frequently, try posting it on an intranet so everyone has instantaneous access to the changes.
Was this article helpful?