OCaml for the Masses by Yaron Minsky (Appears in ACM’s Queue)
Great article and merits a close read.
As does the first comment, which gives a concrete example of “readable” code not preserving even for its author, “why” a particular code block was written? As the commenter points out, literate programming is the key to capturing “why” code was written, which is a prerequisite to effective long-term maintenance.
Curious what you see as the upsides/downsides to using topic map as overlays on code to provide literate programming?
True enough, it is “quicker” to write comments inline, but are your comments consistent from one instance of being written inline to another? And do your comments in code tend to be briefer than if you are writing them separately? Or are you deceiving yourself in thinking your code is “commented” when the comments are as cryptic as your code? (Not that topic maps can help with that issue, just curious.)
I see downsides in the fragility of pointing into code that may change frequently but that may be a matter of how pointers are constructed. Could experiment with strings of varying lengths as identifiers. If of sufficient length, do you really want to have different documentation for each instance? Hmmm, could create identifiers by highlighting text and after some time period, app returns you to each of those so you can write the documentation.
Other upsides/downsides?