Brian's rant about comments in code

Just because I've said this a few times and am tired of retyping it:

The problem with commenting functions is that you have to already know what function you have to use, in order to find the comment that tells you. Much better would be to have a separate, coherent document that teaches the program structure, with annotated examples that transcend a particular function. More like "suppose you want to..." and then a walkthrough of inventing code to do that.

Sorry, you pushed one of my buttons; I'm fanatical about this because everyone else who teaches programming disagrees with me and likes lots of comments in the code. So, here's how I think about it: A program is more or less a tree structure, in which the top level is a big module with a particular function, perhaps it's one file in the source code, and then underneath that there are medium-size chunks, possibly including object definitions if it's an OOP-style program, and underneath that come the individual interface procedures that expect to be called from outside the module, and then underneath that might be subprocedures that are part of the implementation of some interface and don't expect to be called by anyone else.

So, in a perfect world, programmers would provide documentation in a parallel tree structure, with documentation at every node: the program as a whole, its large modules, its medium-size chunks, etc. But programmers are notoriously lazy about documentation, so you're not going to get them to write all of that. So, which piece of it should you ask for? I argue that the best thing would be really good documentation at the top couple of levels of the tree: documenting each module, and documenting the big chunks within each module. Instead of that, teachers insist on getting the least useful kind of documentation, namely details down at the leaves of the tree.

When I was working at IBM (every programmer my age has war stories about having worked at IBM), for every customer-visible program there was a document called the Program Logic Manual that you could buy, just like the user-oriented manuals. Those were the glory days of documentation! Nobody does that any more, more's the pity.

This is extracted from Tedious but fun little sequencer project - #25 by bh if anyone cares about the context.