This topic has been the source of many spirited conversations where I work. What goes into a design doc? What goes into a user manual? What is the appropriate level of comments for code?

I personally find that a user manual should only tell the user what they need to know to use the tool (or library, or module, or class...), not anything about the internals (too much information, and the documentation won't be read). POD seems to be a useful way, and I would always recommend it.

When it comes to design documents, some people I work with state quite emphatically that their design document is the comments in the code. IMHO this is not sufficient. If I suddenly have to maintain someone else's code, a roadmap would be nice (i.e. these files contain the code that does x, so if x breaks, this is where to start). After that, the specifics of the design I do expect to find as comments within the code.

With regards to comments in the code, some of my co-workers write books at the header of each function/class. Others insist that there be a comment for practically every line of code. I, however, being rather old school, learned my habits before syntax highlighting full screen editors were available. The criteria for my commented code is: (1) use lines to outline main comments, and (2) the comments should read like a very general algorithm.

The reason I like my commented code to read like an algorithm is very simple. When I go back to it to add new stuff (there are always new requirements) or especially when looking for a bug, I can verify that the code does what it is supposed to do (as determined by the comments). If I don't know what it was meant to do, then it is much harder to know whether or not what it is doing is what it should be doing.

I have written parsers (in FORTRAN for FORTRAN) that would extract the comments, and then used the results for detailed design reviews. I found this to be very useful. To this day, before I consider a project finished, I will pass through one more time, ensuring the the comments reflect the intention of the code.

to include such documentation means to balloon the size of the source code

Sandy