Response to “Literate programming considered harmful”
johnwshipman.blogspot.com
Response to “Literate programming considered harmful”
1–10 of 68 posts
Re: Response to “Literate programming considered harmful”
#2I 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?
Re: Response to “Literate programming considered harmful”
#3I 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?
Good question, and what of doc generators like Sphinx that create web pages with those comments plus the method code it came from?
Re: Response to “Literate programming considered harmful”
#4Is programming harmful?
What question is that?! If you write malware with it, yes it is! Though not for you.
Re: Response to “Literate programming considered harmful”
#5I 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?
"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.
Re: Response to “Literate programming considered harmful”
#6The trend in programming lately seems to be less to no comments and less to no documentation; and it is killing the joy I take in programming. Without comments the only way the next guy has a chance to understand the code is if you stick to lowest common denominator patterns and frameworks. You can't do anything that hasn't been done before.
I think this is related to the proliferation of frameworks. I can't come up with my own pattern that best fits the problem, but I can select from a list of pre-approved patterns in our framework and shoehorn the problem into it. We only hire people familiar with the framework, so no need to document.
It really comes down to laziness. A literate program demands you put forth the effort to understand it and read the docs and code. Whereas a with a framework program you can copy and paste code from blog posts and stack overflow without any clue what is really going on.
Re: Response to “Literate programming considered harmful”
#7I 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?
I 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.
Re: Response to “Literate programming considered harmful”
#8I 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?
No. 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.
Re: Response to “Literate programming considered harmful”
#9Is programming harmful? What question is that?! If you write malware with it, yes it is! Though not for you.
They're just using a headline derived from Dijkstra's "Go To Statement Considered Harmful". As with Dijkstra it's a bit clickbaity i.e. they really mean use with care rather than harmful.
Making it a question just gives the extra benefit of making it likely to conform to Betteridge's law. So a meme win-win really.
Re: Response to “Literate programming considered harmful”
#10I use literate programming for "research" projects - I use emacs org mode with org babel and ob-ipython. It is useful for that purpose, as I am usually chasing a few options in parallel and results later will need to be presented to the team.
When project wasn't that researchy in the first place (does not require significant experimentation to come up with the solution), or exits the research phase I move to standard programming tools.