Does Code Belong in Essays about Software?

When I wrote Can I Do Without This, it struck me how hard it can be to describe software. In the draft I described a real-world case, detailing how I took the principle I espoused in the essay and applied it to the software I am currently working on. I had to delete those paragraphs. The details distracted from the flow of the writing. I could not make them comprehensible to the reader without going off on a tangent to explain all of the made-up terminology that describes my classes and methods. Software is difficult to describe. I want to speak in specifics, but writing in plain English constrains me to generalities.

Source code exists for the specific purpose of describing programs. Algol (one of the earliest high level languages) was originally invented for the purpose of making it easier for computer scientists to communicate with each other in publications.

However, source code is not English, no matter how many pains you take to make it appear so. Source code is a form of notation, like mathematical notation or musical notes. Good advice for research students is to try to avoid putting math on their slides when they make presentations, lest they lose their audience's attention span. I think the issue is not just math, but that any form of notation is a denser form of communication than what humans are comfortable reading - too dense to put into an essay.

There are other reasons not to mix code with ordinary writing. The formatting that is applied to prose will severely damage the careful indentation structure of a source code example. Conversely, when the source code gets its own formatting, the breaks introduced by switching back and forth rapidly are jarring.

Code and prose don't mix well. This is a real problem if code itself is the subject of your writing. Ultimately, though, we are deluding ourselves if we think that someone is actually reading all the code examples, if we include them. Source code is to be read in the context of pursuing a bug fix or feature change in real source code files. I don't read other people's code examples in literature - why should I be inclined to think that other people will really read mine? When I started this blog, I knew that this issue would surface. I made a decision that I would focus on the articles more than the code examples. It's more readable.