the title of this writeup reminded me of this recent IOCCC winning entry

*g*

I've hacked a working prototype module for internal discussion. The header file has about 300 lines of Doxygen documentation and about 30 lines of code, mainly function prototypes and macros. The source file has about 40 lines of code, plus a little bit of doxygen documentation.

Compared with our other modules, the relation between documentation and code in the source file is normal, may be a little bit short, but the documentation of the header is unusually verbose. Typically, the doxygen lines are twice or three times the number of code lines.

The prototype is still a little bit rough, it still needs some paranoia checks and some cleanly documented ways for advanced use of the mechanism. That will increase the code size by about 20 lines and the documentation by about 100 lines.

So yes, some parts of the code may look like coming from the IOCCC, but it's only the code. The documentation explains what happens, why and how, as usual for our projects.

In fact, I actually use code from an IOCCC winner at work:

IOCCC winner 1984

int i;main(){for(;i["]<i;++i){--i;}"];read('-'-'-',i+++"hell\
o, world!\n",'/'/'/'));}read(j,i,p){write(j/p+p,i---j,i/i);}
[download]

It's in a presentation for interns and freshly hired people, on one of the first pages, right after a picture of the HGTTG with the "don't panic" in big friendly letters. That piece of code is a really good example of bad code, on many levels. What follows is an introduction to the way we write code and documentation, why and how we do it, which modules are a little bit special, common errors, trouble with legacy code, and how to debug.

Alexander