3 ms·
I have never used Ada. But I really like the idea of having implementation documentation separate from interface documentation, and treating it like real docume
by nerdponx 5y ago
I have never used Ada. But I really like the idea of having implementation documentation separate from interface documentation, and treating it like real documentation with its own searchable/linkable HTML or PDF reference document.
A good IDE can then fold/collapse the in-code documentation, and the programmer can have it up in a separate window along side.
This could be an interesting model for literate programming. Instead of it being "linear", like reading a novel, it would be like reading a translation of an ancient text, with the original source material on one side of the page and both the translation and detailed reference notes on the other side. And of course there would be a hypertext component to the documentation, which would allow you to build a "table of contents" and jump around the codebase.
- masklinn 5y ago> This could be an interesting model for literate programming. Instead of it being "linear", like reading a novel It's unclear what you mean by "linear" here. Surely your "translation of an ancient text" is a linear read following the "ancient text" it translates even if it has forwards and backwards references? Knuth's original conception of literate programming was non-linear in terms of code, you'd write some text, write some bits of code, possibly add a reference to an other snippet, write some more text, write some more bits of code, and tangle then stitches the source back together by following references. More "modern" literate programming is non-linear in terms of narrative, making the "comments" / "docstrings" the main content but then having the code execute "normally" ignoring said comments. Jeremy Ashkenas's tools (e.g. undescore, backbone, …) are all written and published in that style even though Javascript is hardly conducive to it, and shown in exactly the "original source material on one side and translation and detailed notes" you seem to talk about on the other. That is what Ashkenas called "annotated source": https://backbonejs.org/docs/backbone.html https://backbonejs.org/docs/backbone.html, https://underscorejs.org/docs/underscore-esm.html https://underscorejs.org/docs/underscore-esm.html. Recent revisions of underscore have been modularised and show individual segments you can look between instead: https://underscorejs.org/docs/modules/index-all.html https://underscorejs.org/docs/modules/index-all.html maybe that's what you're thinking of when you talk about it being non-linear? It's missing some of the bits e.g. the symbols themselves are not hyperlinked and there is no glossary, but because in the modularized version each function is the sole export of its module it's easy to jump between functions. Not that I'm convinced this makes for a great experience as it requires keeping a lot in memory, but there you go.
- nerdponx 5y agoI meant "linear" as in you start at point A and read until point B. That is, pieces of information are presented and organized as a sequence of one item after another. I am envisioning a system where the programmer has code in one window and the explanation of the code in another. Like a book with text on the left and annotations on the right.
- masklinn 5y ago> I meant "linear" as in you start at point A and read until point B. That is, pieces of information are presented and organized as a sequence of one item after another. That is the definition of the word, it’s not actually helpful in understanding what you’re thinking about. > I am envisioning a system where the programmer has code in one window and the explanation of the code in another. Like a book with text on the left and annotations on the right. So… literally what i posted.