Documentation with Code

[AndrewBarnard]

An approach to documentation with code

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 humans what we want the computer to do. (Donald E. Knuth, 1984).

This introductory comment represents a significant change of perspective. In the construction of programs, rather than focussing on the task of instructing a computer what to do, we are encouraged to focus on the task of explaining to humans what we want the computer to do. The result is not just instructions for a computer, but importantly, perhaps more importantly, an explanation that will guide other humans to understand what we want the computer to do.

One common approach is to annotate the computer program with comments. Putting aside the obvious problem that the comment and the code may differ - leaving the reader with the challenging of guessing which is authoritative - comments are at best clumsy. The fundamental weakness of comments is their physical proximity to the code. Although a comment may be useful to explain the finer details of the code close to where it is placed, remove the comment from that place and the comment becomes far less useful. Using comments to tell stories for humans imposes the structure of the code upon the structure of prose. A less than ideal restriction when structuring an explanation for humans.

Another common approach is to write documentation outside the code. Whilst this approach provides flexibility in the structuring of the prose, the obvious weakness is the independence of the documentation from the code. The documentation is one artefact and the computer program another, often written with different tooling - and both are independent of each other. The code can change, and the documentation remains unchanged. Or the documentation is revised, but the code is not. And if code is to be referenced in the documentation, the author typically reverts to images or copies of the program source. Writing a fulsome explanation in prose with interwoven code becomes a challenging task.

An approach?

Rather than embedding source code in documentation or documentation in source code, a useful approach might be that taken by the Open Source tools verso and recto. Verso | Recto. In the verso | recto world view, a prose document refers to source code and interweaves source code sections into the prose document.

The verso program extracts fragments of code from source code. Fragments of code are identified by annotation symbols denoting the start and end of the fragment. The annotated fragments are given IDs which are referenced in the prose documentation. When executed, the verso command extracts fragments of code from source files.

The recto program inserts the fragments of code into the correspondingly annotated sections of the documentation.

Both tools are designed according to the Unix tools philosophy. The output of verso serves as input to recto.

A short usage example

Assume we have an ABAP source file named PERIODS_TEXT_GET with some fragments of code identified by annotation symbols. We also have a Markdown document in which we seek to explain our intentions with the function group CR02. We wish to interweave source code in our explanatory document.

Here is an example invocation:

verso ./CR02/PERIODS_TEXT_GET.abap | recto ./Documentation/ CR02.md

The command above parses the source file PERIODS_TEXT_GET.abap, extracts the fragments, passes them to recto which in turn weaves them into the Markdown document CR02.md and places the resulting document into the Documentation directory.

Voila!

Some not so Frequently Asked Questions:

Q: This approach relies upon parsing ABAP source code using command line tools. How do we get ABAP source there?
A: You might use abapGit or the ABAP report RSDUMPSOURCE to download source to a file system.

Q: The ABAP source needs to be annotated. Will this interfere with the ABAP compiler?
A: No. The annotations are treated by the ABAP compiler as comments - they are simply ignored.

Q: recto produces Markdown. I'd prefer HTML or other formats.
A: Markdown lends itself to transformation to HTML and many other formats.

Q: Is there an ABAP version of verso | recto?
A: No. It is written in the rust programming language. The source is available.

Final words

Documentation generation from code comments is a fairly common thing nowadays. Many languages, such as Java, ABAP, JavaScript, python and rust, all have tooling to generate documentation from well constructed comments in the code. This is very useful.

The intention here is somewhat different. The goal is to reference significant or important sections of code and insert them into documentation written by a human. Documentation explaining design decisions or implementation details of the code.

I find the idea intriguing and potentially very useful. What about you?

This article was written, edited and spell checked using Vim text editor.

:wq