Title: Professionalism in Programming #5

Well, presumably we write code for 'customers'^[1], so we are hopefully aiming for the latter. My question more specifically is: do we write code for it to be read by computers or humans?

We certainly write code in order to instruct a computer what to do. But we are actually writing code to express the concepts in our heads, to describe the way we want to mould the flow of execution and how to manipulate the data structures we have generated.

I think it is fair to say that machine code is supposed to be read by computers - it is the language of the CPU. You cannot talk to a microchip in English, after all. However, any higher-level language like C or C++ is removed from the machine code by a number of levels^[2]. When we write code in these languages do we really write for the computer? It is more accurate to say we write code for both ourselves and the computer.

However, we are writing the code in a more human-friendly way, primarily for ourselves. We then get a compiler to 'translate' our human-friendly language into computer-friendly language the CPU can understand. In this respect, the programming language we choose has been designed so that we can talk to the machine. But it has been created mainly so that we can convey our thoughts and concepts in a natural manner for us.

So then, programming languages are how we express our programs, both to the author and for the (human) reader. We use programming languages to prevent ambiguity. We use them as concrete documentation of the algorithms we choose.

So if we are writing code for humans to read, we should be taking care to make the code as clear as possible, and as easy to understand as possible. By necessity the code is something that more people than just the author must be able to understand. This actually is not that hard to do, and takes little effort. By improving the ease of understanding of the code we write we gain a number of benefits:

Remember that computer programs are inherently much harder to read than they are to write. Anyone who has used Perl will understand this. Perl has been described as the ultimate write-once language. If you come back to some of your old Perl code, or look at someone else's, you'll be lucky if you are able to understand it.

It has been argued that the only document that explains some code completely and correctly is the code itself. This is one of the Extreme Programmer's axioms [BECK]. It is certainly true, but it does not necessarily follow that it is best description possible. Whether you are using that as an excuse (sorry, reason) not to write a specification or code comments, or believe that we should still write supporting documentation, it is clear that we will benefit from writing code that is as self-documenting as possible.

By 'self-documenting' code, I mean easily readable code that stands comprehensible on its own. We can improve the clarity of our code in many ways. Some are very basic and have been drilled into us since we were taught to program. Others are more subtle and come with experience. For example:

Literate programming is a term coined by the renowned computer scientist Donald Knuth; he wrote a book by this title [KNUTH] describing it. In many ways it is a quite radical alternative to the traditional programming model, although some think that the literate programming episode of Knuth's career was a large and unfortunate sidetrack. Even if it is not the One True Way to code, it does not mean that there is nothing we can learn from the concept.

The idea of literate programming is simple; not only is the source code written for humans to read, it is embodied in the system documentation. The documentation language is bound up tightly with the programming language. You write one file that is primarily a description of what is being programmed, but also happens to compile into it. The source code is the documentation.

It is almost written as a story, it is easy for the human reader to follow (perhaps even enjoyable to read). It is not ordered or constrained in any way to make it easy for the computer to parse. This is more than just a language with inverted comments! It is hard to describe when we think in our traditional file-based programming paradigm, literate programming is a whole different way of thinking about programming.

Knuth originally mixed T_EX (a document typesetting mark-up language) and C in a system called WEB. A literate programming tool parses the source file, and generates either formatted documentation (printable or HTML, for example) or source code that can be fed to a traditional compiler.

Of course, since this is just another programming technique, like structured programming or object oriented programming, it still does not guarantee quality documentation. That is, as ever, up the programmer. However the technique shifts emphasis onto writing a description of the program rather than just writing code that implements it.

Literate programming tends towards keeping the documentation consistently accurate - it is updated with code, since it is right beside the code. Many programmers will tell you from first hand experience how easy it is to forget to update a separate specification when you modify some code.

Literate programming also encourages the inclusion of items not normally found in source comments, for example a description of algorithms used, proofs of correctness, and justification for design decisions. This sort of documentation can be included without cluttering source with random comments or bogging down a specification with many issues about specific bits of code.

During the maintenance phase of a product literate programming really comes into it own. With good quality (and quantity) documentation directly on hand it is much easier and cheaper to maintain the source.

Some literate programming tools can include pictures and charts in the source. They allow you to do clever things like describe a C++ class in its entirety (i.e. both interface documentation and implementation documentation) in one source file, and have the tool split it out into the .h and .cpp files for you.

In the third article in this series [GOODLIFFE] we discussed software specifications. So how does literate programming relate to specifications? A literate program will never replace a functional specification describing what work needs to be done. However, it may be possible to develop a literate program from such a specification. The literate program really is more of a combination of the traditional code with the design and implementation specification. See [MALL] for more information on literate programming.

There is a breed of programming tool that is a sort of halfway house between writing separate specifications and the literate programming approach. They are greatly gaining popularity. These are tools that generate documentation from your source code. The documentation is pulled out from blocks of specially formatted comments that you write. This has perhaps been particularly fashionable since Sun introduced the Javadoc™ program [SUN] as a core component of the Java platform. All of the Java API documentation is created automatically by Javadoc™.

For example, to document a Widget class, you would write something like:

/**
* This is the documentation for the Widget
* class. The tool knows this because the
* comment started with the special '/**'
* identifier.
* @author Author name here
* @version Version number here */

class Widget {
public:
/** * This is the documentation for a method. */
void method(); };

A documentation tool will parse the file, and extract the documentation information, building a cross-referenced database of all the information it finds on the way. Then it will spit out a document (either online or hard copy) containing this information. This is most likely API documentation rather than implementation documentation.

There are a number of such tools available today. Many of them are open source and widely used. I list below a number of them and provide a simple comparison of features (E&OE!). I have never used any commercial documentation packages - the free ones are so good I would like to know what the commercial offerings provide (apart from fancy GUI front-ends). If any readers have experience with them then I would be glad to hear about it.

It is worth noting that most of these tools do not support Java since the language already comes with a de facto tool.

Writing code is not just about typing fors and switches into a text file. And it is not all about the high level design, either. A good programmer who takes pride in their professionalism is careful to write code that can be easily read, aiming for it to be self-documenting code. We write code primarily to communicate.

Literate programming is one (quite extreme) method of writing self-documenting code. Another less extreme method involves using documentation tools. These tools can generate API documentation very easily, but they do not necessarily take the place of a well-written specification or other descriptive document.