I was taught this same lesson by a firmware programmer who didn't want to read the documentation for the hardware that I had designed. He just wanted to look at my schematics!

I like to have one comment at the top of each file that says what the program or module is supposed to do. I also like to comment my bugs or poorly written code. I can tell that the code is okay when all of the comments are gone and I can still easily read the code.

If the code is a module that is intended to be used more than once, writing the pod documentation is still a good idea. This is different from code comments, though. If the module is well-written, it probably won't be subjected to cut-and-paste, it will get used properly.

It should work perfectly the first time! - toma