coders at work

On Writing Documentation

I've been slowly reading through "Coders at Work," an excellent book in which Peter Siebel interviews many different programmers on their work and craft, and I hit a great little snippet of advice from Peter Norvig:

"The overall design of what's going to do what, that's really important to lay out first. It's got to be something that everybody understands and it's also got to be the right choice."

Basically, before you start doing some huge project, have a bit of a meta discussion about what you're trying to do. Document the process / steps, make sure it makes sense, and code to that process. You don't need to necessarily comment on every little tidbit of code you write—code should be somewhat self-explanatory if written well—but you should at least document what your functions do, and what kind of idea you're trying to implement.

Plus, if you document beforehand, you'll be able to conform code to documentation, and at the end you'll have a framework of your docs already complete!