Literate Programming is a technique which was introduced by Donald Knuth in 1984:
I believe that the time is ripe for significantly better documentation of programs, and that we can best achieve this by considering programs to be works of literature. Hence, my title: "Literate Programming."
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.
The practitioner of literate programming can be regarded as an essayist, whose main concern is with exposition and excellence of style. Such an author, with thesaurus in hand, chooses the names of variables carefully and explains what each variable means. He or she strives for a program that is comprehensible because its concepts have been introduced in an order that is best for human understanding, using a mixture of formal and informal methods that reinforce each other.
The key idea here is that the programmer is tasked with writing documentation that compiles into code rather than writing the code and attempting to document it separately.
At the other end of the spectrum is the imaginatively named Reverse Literate Programming. This tasks the programmer with writing code that is directly compiled into documentation. This is likely to sound quite familiar as systems like Javadoc enable API documentation to be produced by compiling program source code. However, API documentation alone is not enough as it is focused on the minutia of source code rather than any high level details. Package level documentation can be added but this isn't very accessible as it is stored in a separate file.
Code Trails
I think IDEs need to do a better job of making it easier to provide simple high level source code documentation.
The use of markers within code comments allow key locations within code to be highlighted. The IDE collects together these markers into Trails that are displayed together. These Trails provide simple high level documentation and every marker can be double clicked to quickly examine the code at the location of the marker.
What does this look like in Eclipse? Here is some example code:
And the corresponding Trail view:
Installation
If you are interested in trying out the Code Trails plugin you can install it from my update site:
http://mchr3k-eclipse.appspot.com/
When you first open the Trails view you will get the following warning about needing to run a full workspace rebuild.
