So, you'ld take a single line cryptic comment, scribbled as an afterthought by the original coder, over a well documented formal interface specification, written directly above the function declaration, and visible to the maintainer in question? Nice.

But the comments merlyn was making weren't intended for the user (then they would be in the POD) - they were there for the (maintainance) programmer. Two very different beings. With different needs. And different documentation.

*sigh* That's why my usage of POD allows for two classes of documenation, due to the two different intended audiences.

I note that you carefully excluded the most important audience in your little diatribe. What about the testers: you know, the ones who's job it is to verify the code against the comments, and bitch if they find any flaws? When the interface is well documented, the code can't fall out of spec with the interface documentation, because it's a flaw in the code or the interface if it does. The testers can verify this without reading a single line of code; this helps keep them independant of the coder, and the codebase.

I hope I never ever have to maintain your code.

The feeling is more than mutual. You've stridently and vehemently opposed a form of literate programming that allows for clearly documented interfaces, eases the burden of unit testing, and provides a formal mechanism to ensure that the code matches the comments, none of which you provide cogent alternatives for.

If I want documenation on a function, in my code, I just run a script, and read the docs. I can even auto-extract the call tree for my program, and generate a hierarchical set of documentation by function for every function in my program, and how it should be called, and why. I can choose to just display function purpose overviews, drill down into the calling requirements, or even link back to the matching section of code to check the implementation details.

I can give it to someone else to sanity check flow and the logic, or show it to the maintenance programmer so he can get a comfortable view of the what of the program, without getting bogged down in the how

By constrast, you've just got a big mass of implementation details, with a few unverifed comments scribbled in by the coders when they have the time. To decipher how your code works, I need to search for the appropriate function, and start guessing about whether your comments are correct or not, double-check the test suite to determine whether or not it's up to date with your latest comments, see if the comments seem to match the code, reverse-engineer the proper specification documentation (that you oh-so-proudly didn't write), deliver it to the testing department, and keep it all up to date manually. Or just give up on it all, because it's "too much work" when you have to start verifying everything from scratch each time.

Comments should be right there where the code is, and not somewhere tucked away where I need a different tool to read them.

Yes, a difficult tool -- called a scrollbar. I can see how that would be hard, especially considering the terrible information you might be exposed to. Oh, no! You might be able to view the entire purpose of the function in a unified context, all it's required inputs, required output, intended use, and error handling specifications, as opposed to the joyous challenge of deciphering the unstated intent of some ugly mass of code. Horrors!

--
Ytrew