
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.
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.
verso ./CR02/PERIODS_TEXT_GET.abap | recto ./Documentation/ CR02.md
This article was written, edited and spell checked using Vim text editor.
:wq
You must be a registered user to add a comment. If you've already registered, sign in. Otherwise, register and sign in.
User | Count |
---|---|
7 | |
4 | |
3 | |
3 | |
2 | |
2 | |
1 | |
1 | |
1 | |
1 |