in reply to
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
It should work perfectly the first time! - toma