Documentation improves code

Volume 4, Issue 31; 20 Jun 2020

It is an underappreciated fact that writing documentation improves your code.

The observation that documentation improves code is hardly ground breaking. I believe I’ve heard it argued that the TeX formatter, a large and complicated system, had very few bugs because it was written with a literate programming system. Literate programming is sort of the ultimate in documenting code: the code and the documentation are literally intertwined.

I’ve tinkered with literate programming over the years,Walsh, Norman. Literate Programming in XML. Presented at XML 2002. 15 Oct 2002. most recently using Org-mode for some python scripting and my .emacs file, but it’s never really become a habit that I apply broadly. I’m not convinced my excuses would stand up to hard scrutiny.

Programmers are often reluctant to spend time writing documentation. It’s not seen, I think, as being a productive activity the way programming is. It’s also hard. Writing is hard.

But I’ve been getting up early in the mornings to write some documentation to round out the work that I’ve done for my Balisage paper. I found another bug this morning because I was writing documentation. Writing documentation required me to write down what the code was supposed to do and looking at the code made it clear that it didn’t. I don’t know if I’m into double-digit bugs fixed because I was writing documentation, but it’s definitely more than I could count on the fingers of one hand.Ignoring dactylonomy systems that allow you to count to more than five with one hand. Write documentation.

The particular bug I found just before I started writing this post was an XSLT template in a mode that was never used. There are no bugs in deleted code.

Now, back to writing documentation.