After years of doing software maintenance of other people's code, my doc-comments have grown longer and longer. Software maintenance is often the kind of reverse-engineering challenge that Knuth describes in the linked article.

I hate ambiguities and mysteries in code. I make it my mission to provide a complete mental snapshot of the domain knowledge required to understand anything I write.

My doxygen doc-comments of C++ namespaces and classes have grown to the length of short blog posts containing a comprehensive introduction and overview to the topic, replete with links to external references.

Some programmers probably hate me for this. Maybe a few love me.