A programmer colleague once observed, “You get more out of a line of code than anyone I know.” At various times this has felt like a criticism, at others, like a complement.
Note that my code was not obfuscated or deliberately opaque, it just had the fluff and the fat trimmed out. No dead code to be eliminated by the compiler. If the whole equation fit on one line, it was on one line. Etcetera.
When I first started writing technical articles, I found that my first drafts were too dense for easy readability by a factor of about two. Essentially, there was no redundancy. Every idea was there once, precisely expressed, each word selected for exactly the right meaning. It makes it just about impossible to contradict myself, but the reader has to understand each word exactly the same way I do. And there is no redundancy to help correct misunderstandings. So that density of writing is not desireable in explanatory or tutorial writing.
So a question is, where is it appropriate? Or perhaps, where is dense/rich expression used?
- Math and Science: think how much verbiage has been written explaining e = mc2 or the wave equation in quantum mechanics.
- Standards: here the lack of redundancy may be deliberate so the standard can’t contradict itself. There is often an unofficial section explaining the official section. Standards aren’t light reading, readers are expected to already be an expert, and a glossary in the back explaining terms is acceptable. There are standards for standards! ISO standards in English are required to use British spellings.
- Poetry: same as math and science. Especially if it is not written in contemporary English. I read an analysis of Dante’s Inferno that devoted a page and a half to the first four lines of the original Italian, explaining the exact meaning of the words and their connotations.
- Sacred Texts: same as science, math, and poetry combined. I recently read an analysis of the First Pillar of Islam, six pages to explain two short sentences of Arabic.
Admittedly my code is not as dense or rich as any of these, but what can I learn from them about writing rich code?
Maybe the solution is to write the code succinctly, with no wasted motion, no superflous lines, use good formatting and naming conventions. And then write a commentary on it. Supposedly comments and documentation do this, but in my experience, not enough effort is put into them. Too much commenting obscures the code. Not an improvement. Documentation is separate from the code and often the distance grows as the code evolves and the documentation doesn’t. Donald Knuth’s Literate Programming is a good, though partial solution.
I’m not sure what the solution is, but it isn’t dumbed down code.