In the early 80s, people were concerned about the maintenance of code just as we are today. One effort to improve the readability was to format a program like writing an essay. We have to pay attention to the language, compiler, architecture, and machine when we write a real program, but a logical flow of thought understanding is not supported well by typical program construction due to these extra elements that must be regarded. Literate programming [1] was meant to allow you to pay attention to the logical flow of the program. In 1990, Oman and Cook performed a study [2] on code written in the style of a book with paragraphs, chapters, indexes and such-somewhat like Literal Programming. The results were very positive. For example, they gave maintenance tasks to programmers who were experienced with a code base and those who were not. The programmers who did not know the code base were given the book format for the code. The experienced programmers were not. In this test, the non-experienced programmers performed as well as or better than the experienced programmers!
While Knuth [3] is given credit for being the first to create literal programs and tools to develop them, a small crowd has continued with the concept. nuweb [4] is a program to aid in creating literate programs and I used it for my journey into this area.
The process of literate programming is to create a single document containing both the code and the documentation. Since the code can be broken up into snippets and arranged in any order, the flow of the document can follow your logic or the problem instead of the software language. Eventually, when you are done, you can run the nuweb utility on your document, which will split that document into a readable documentation document and the code files for your program.
Since writing code comes naturally to me, I wrote my code first. Then, I documented everything in a nuweb document. A nuweb document (has a .w filename extension) is a LATEX document with some extra tags for the nuweb application to specify code fragments and files. After that, I ran the nuweb utility which outputs a cpp file and a tex document which I then ran LATEX on (Figure 1). For me, it seems that this tool is best for documenting large program or complex programs.
I currently participate in the codingame [5]; an algorithm writing website. For my nuweb project, I just took a program from my codingame and wrote the literate document for it.
I chose to work on the APU: Init Phase codingame challenge. First, I put the explanation for the game into the document. Then, I added my solution with appropriate explanation and code snippets. Since my code had been done before, I just copied parts of it into my nuweb document to get the snippets. All in all, I found the process simple to do. You can see an example of the nuweb document here main apu initv3.w. This then compiled into main apu initv3.tex and main apu initv3.cpp. And finally, I processed the .tex document to get main apu initv3.pdf.
The benefits here seem to be that you can document your program in a complete way with one document. Although programs are documented, we generally need to jump around the code and put it together in our heads. Having one document for the entire code base with links and indexes can help. Another benefit is that nuweb uses LATEX, which is a great document creation language and this allows you to add tables and figures to your software documentation. Other options include writing your code in a way that documents it. You can also use tools like doxygen [6] and JavaDoc. There are also formats for documentation like the SCR method which have shown a lot of promise for specification and readability [7]. Another option is to create a model as the documentation and to generate code from it.
The drawbacks of Literate Programming seem to be that it is focused on an artistic view of software creation. This brings the associated sloppiness and reliability issues of much of this type of software, which is unacceptable in many areas such as airline control software. However, for other software areas it is appropriate. Secondly, it does require the user to be able to know how to write well enough to create document that is helpful.
The impacts of this type of programming are that your documentation and program code will likely be improved. In the short term, just the process of creating such documentation helps the creator. Additionally, with nuweb's reliance on existing tools such as LATEX enable it to be a persistent solution that you can be confident will be able to last a long time. Long term impacts are that these Literate Programming documents can greatly ease maintenance [2], especially for complex or large programs.
In my personal opinion, I liked the resulting document that was created. It only had the essential elements that needed to be described. However, I do not think it was so useful on this program. Literate programming seems to be suited for really complex code or larger programs. After writing a program and coming back to it years later, it always takes me some time to get familiar with it again. Literate programming would speed this up and that would be great for my maintenance tasks. When I say it would be good for complex code, I mean algorithmically complex, or accidentally complex. Accidental complexity such as the obscure coding for Windows batch files can really be tackled with literate programming.
Currently, my meetup group DevTalk LA, is reading Clean Code by Martin [8]. I find Bob Martin to be a good communicator, but he also seems subjectively focused on object oriented Java code as being some ultimate paradigm for software. While his book has good points, I find that Code Complete [9] applies to OOP and other paradigms. Additionally, that book provides proof from actual scientific studies for the viewpoints it espouses. While both of these books encourage the programmer to write readable code, that viewpoint sometimes gets in the way of abstraction. Literate programming, by separating the documentation and the code, enables a much more flexible way of documenting a program.