In some email I received from der Mouse, sie wrote:
[Charset iso-8859-1 unsupported, filtering to ASCII...]
> > I hate mandatory comment blocks before functions!
> 
> I hate mandatory just about anything.  As soon as you require any sort
> of documentation, much of it tends to be of crappy quality.  Lots of
> coders, unfortunately, can't write documentation to save themselves; if
> you require them to try, you'll get bad doc.  (Fortunately, there are
> others who _can_ do good doco....)
> 
> All the rules in the world won't get good doc out of someone who can't
> (or won't) write good doc.  And a good documenter doesn't need the
> rules, and in fact may be hampered by them....

The idea is not to produce documentation but to make pre-function
paragraphs of comments useful for other programmers so they don't
need to waste time trying to work out what code does or come to
the wrong conclusion.

> I've written one-line comments for whole-screen functions, and
> conversely I've written multiple screenfuls of comment for ten-line
> functions.  It's all a judgement call....

Right.

Me, personally, I'm still experimenting with what looks good & bad.
But one thing I have noticed, it becomes much easier on the eye when
you have "drawing" when spotting function boundaries.

Darren