4 ms·
I definitely find literate programming intriguing. I like stuff that's well documented and I find my own documentation crucial for understanding things. I am
by wodenokoto 10y ago
I definitely find literate programming intriguing.
I like stuff that's well documented and I find my own documentation crucial for understanding things.
I am however a bit at a loss about the practicalities.
Does writing a doc-string for each class/method/function and connecting to readthedocs count as literate programming?
- dpedu 10y agoGood question, and what of doc generators like Sphinx that create web pages with those comments plus the method code it came from?
- js8 10y ago"Does writing a doc-string for each class/method/function and connecting to readthedocs count as literate programming?" I don't think so. It's like comparing the Lord of the Rings, the novel, with the index that contains descriptions of all the characters in the Middle Earth. I mean both tell you the same story, but from a very different perspective. I am personally not a fan of (what I understand as) literate programming, unless you are writing a piece of educational code that is supposed to be read from beginning to end (like Jones Forth, for example). What I think should be done instead, the code should be documented on several levels, each level more detailed by a constant factor. So each couple lines should have a comment, each function should have a comment what it does with what parameters, each class (or group of functions) should have a description of their purpose, each module should have a description of its architecture and interactions, and so on until you would get to the top level architecture. So it would be more like a tree of more and more detailed documentation rather than linear novel that you read from start to end.
- throwanem 10y agoI would not say so. (I would also not say you should stop doing that!) In my relatively limited experience of literate programming, it adds unique value in two ways: 1. By embedding code in a narrative which, when lucidly written, yields context and understanding of what it does (and doesn't do) and why, which is far superior to what a later developer could derive purely from analysis of the code and whatever other artifacts exist around it; 2. By using capabilities like hyperlinks, folding, and TOC/outline generation to support much more fluent navigation and autotitration of complexity than are possible without. Learning and using tools which support these capabilities is undoubtedly more work than not doing so. Especially in a fast-paced industry environment, doing so is often both hard to justify, and just plain hard - at least in my experience, to do it well you need to be not just a good programmer but a good writer besides, and it is very hard to be that latter thing without the benefit of time to reflect and to edit. But my, again limited, experience suggests that the effort when possible can pay off very effectively.
- Tomte 10y agoNo. Docstrings are nice, but they only (hopefully at least) explain what the current function does. Literate Programming is more about how everything fits together, in /one/ coherent explanation.
- qznc 10y agoThe doc-string state pre- and post-conditions of a function and what it does in abstract terms. It should not say anything implementation specific. For example, the doc string of "search" tells you the returned list is sorted afterwards. It should maybe tell you the complexity of its algorithm like O(n log(n)). It should NOT state which algorithm (QuickSort, TimSort, etc) it uses. Comments in the source code can explain the choice of algorithm.