[kephra]

I've learned coding in Forth, so my code is often creating a domain specific language to solve a class of problems, and Forth shadow pages caused the documentation to be roughly same size as the code itself. But I normally comment in manual style. So the comments in my code do not tell how it works internally, but how to use it, and they are extracted from the code to create a standard Unix roff manual page. I think the Perl community did a good job in constraining a documentation style that is useful for those who want to use a module.

There are seldom exceptions, where I actually comment the code itself. Those are clear warnings that this code is not trivial to understand for average programmers. E.g. my w3dig search engine implements a recursive descendent parser for the site description language, that is not always executed linear, but sometimes pushes a parser class instance together with a closure to a queue, for parallel execution of the spider.