Tuesday, March 12, 2019

Document Before You Start Coding

Wizard writing

This advice will seem strange to some readers, but it becomes natural after being practiced for a while. Comment Before You Finalize Your Code explained why a programmer should document his or her code before finishing it. Document Before You Start Coding goes one step further: Programmers should document their code before starting to code!

After performing detailed design on a component [that is, documenting its external interface and its algorithm(s)], write your inline comments. Most of these inline comments will be nothing other than the previously documented interface and algorithm. Put these comments through the compiler to make sure you haven't done anything silly (like omitting a comment delimiter). Then convert each line of comment into a corresponding program segment. (Note: If you end up with one line of code per comment, you probably specified your algorithm with too much detail.) You'll find debugging goes a lot smoother.


Reference:
McConnell, S., Code Complete, Redmond, WA: Microsoft Press, 1993.