By Jack Ganssle

Writing In Software Development

Summary: It's time we recognize that software development is mostly about writing, not coding.

Let us change our traditional attitude to the construction of programs: Instead of imagining that our main task is to instruct a computer what to do, let us concentrate rather on explaining to human beings what we want a computer to do. Donald E. Knuth

Al Stavely's new book, Writing in Software Development, is a sorely-needed manifesto for the art of writing when creating software.

I read a lot of code and associated documentation, and, alas, find the state of the art to be essentially at a grade school level. It's ironic that engineers produce, more than anything, documents that are supposed to communicate ideas, yet we're so poor at written communication. Al's book is the Dutch boy's finger in the dike, a well-written attempt to show us what we must do.

Some of the book is patently obvious. Much is thought-provoking. The gestalt, though, really defines the essential work of a software developer. It's an inexpensive (as an e-book) work that's a fast read.

The book takes some swipes at sacred cows like C since it "isn't even object-oriented!" C, though, is the lingua franca of the embedded world.

One suggestion is to use a digital camera to capture diagrams drawn on a whiteboard. I first saw this a couple of years ago when working with a lawyer who captured all whiteboard presentations on his camera. Months later he'd still refer to those images. Grey cells are fragile containers of knowledge; digital representations preserve that information for as long as needed.

Another suggestion is to maintain documentation during development, making rough margin notes as you're working, and cleaning them up at the end of the project. I disagree. You won't have time, so those rough notes will be lost. Keep the docs clean all of the time, as we're supposed to do with the code. In other words, keep refactoring the docs.

What about Doxygen? Al likes it, but makes the important point that Doxygen adds no new information at all. It's a useful tool, but no substitute for careful documentation.

Al stresses using assertions as documentation. Parnas said "Just as in other kinds of engineering documentation, software documentation must be based on mathematics." Assertions can be a formal way of specifying the intended behavior of a function. Design by Contract, which takes assertions further by converting them into pre- and post-conditions, is one of the most powerful tools we can employ, both to generate correct code, and to document our intentions.

One interesting idea, drawn from Knuth's Literate Programming, is to write all of our code in a word processor, complete with all of the annotations needed. Using html tags and a relatively simple script, the build process strips the code from the file and feeds that to the compiler. A cool idea, but that generates problems when debugging as the "source" file is not the same as the file used by the IDE. When, oh when, will the compiler vendors wean us from brain-dead text files, and allow us the formatting options we have given the word processing world for decades?

All in all, it's a great read and very worthwhile book. Get it here: http://press.nmt.edu/ .

Published March 14, 2011