Barely Literate Programming

Many of the practical documentation/browsing systems in use achieve little of the promise of LiterateProgramming, but they are nevertheless useful. (The page title should be read in good humour.)

JavaDoc documents primarily the external interface to a method or class, whereas LiterateProgramming ought to describe the whole program. On the other hand documenting the external interface is for practical purposes more important.

The LinuxCrossReferencer?(LXR) provides a hyperlinked web interface to source code in various languages, and integrates with the CVS version-control system. See for example http://cvs.gnome.org/lxr/. LXR points out that a LiterateProgramming system which does not consider version control is perhaps incomplete.

VisualAge pays particular attention to browsing and versioning problems.

Some people say that LiterateProgramming is good if you're writing books about programs, but not if your point is to write programs. I haven't used it enough to comment.

I've recently been noticing one of the things wrong with JavaDoc is that it very strongly concentrates on documenting the code for people who are going to use it as a library. This is a very important thing, of course, but I have TooMuchGuiCode that will never be used "from outside" but which still needs documentation. So I fall back to plain old comments - which are fine, but I hope for something better.

-- MartinPool

I say that LiterateProgramming is good for different uses to different people. There are many different opinions and different ways that literate programming can be used.

What do you mean by something better? To my mind, JavaDoc is almost the antithesis of a LiterateProgramming tool, in that the whole point of it is not to integrate the description and the code, but to be able to remove the description from the code and display it separately.

This would be why it's so great for libraries. When you're using libraries, you don't care what's inside them, and to see what's inside is a distraction. You just want a concise, easy-to-navigate description of the API itself. -- CurtSampson

All of the tools mentioned above work on the basis of abstracting the codebase into signatures (possibly appearing on diagrams), extracting some statically determined dependency information, then allowing the programmer to polish things up a little with some very limited mark-up tags (that are furthermore only tangentially connected with the most trivial aspects of the code's semantics).

What they generate is almost universally "documentation" that meets the need to have some documentation and not much else. By their very nature they conspire against the real need to produce auxilliary documents that help a person playing a particular role perform some particular work with the code. If executed well such documents can be extremely valuable to a development organisation, but the ability to churn out almost completely generic (and therefore almost completely useless) "documentation" with tools like these causes/enables/excuses too many developers never producing the actual documents that are of particular use to the particular people they are supposed to support. Bah!

CategoryDocumentation

EditText of this page (last edited September 26, 2010) or FindPage with title or text search