"The literate programming paradigm, as conceived by Donald Knuth, represents a move away from writing computer programs in the manner and order imposed by the computer, and instead gives programmers macros to develop programs in the order demanded by the logic and flow of their thoughts.[4] Literate programs are written as an exposition of logic in more natural language in which macros are used to hide abstractions and traditional source code, more like the text of an essay."
The key feature of literate programming is separating the order that code is written in from the order that the compiler requires, not comment to code ratio.
We don't need specialized literate programming tools today because modern programming languages are already capable out-of-the-box of sufficient flexibility in organization that the additional marginal benefit of a superspecialized higher-layer toolset to weave pieces together is no longer worth the effort of learning and propagating out to teams. Yes, they technically can do things programming languages can't, but I could even honestly quibble on whether those things are a good idea.
This is why strict Knuth-ian "literate programming" has never taken off on a technical level and why it never will; by the time it might have gotten enough attention to really take off, programming languages had already largely incorporated the necessary additional flexibility that made it unnecessary to use specialized tools to write good code.
The human reason, of course, is that merely making documentation easier or nicer is not generally enough to get people to write it, and arguably literate programming makes it harder to write. Not because of the tooling being bad or anything, but because of the bar being raised really high to have "proper" documentation under its dictates. People can write plenty of well-documented, high-quality code in any modern language right now. They just generally don't.
As evidence of this, compare a well organized C codebase to whatever language that you have in mind. Does it really look that different? Literate programs on the otherhand do like quite different.
Furthermore a big programming project is still just a list of files. What do you read first? What are the important concepts? There is nothing to tell you this information in a typical program. A literate program has a page 1 and you start there. You can think of it like the difference between API documentation, and a well-written tutorial. Modern code files are great API documentation, but are lacking in that other form of presentation.
Another feature modern languages don't have (and probably shouldn't) is the ability to integrate other media types into the code (images, math notation, etc). This is another feature facilitated by literate programming systems, although not the essence of it.
So do I. That's why I said the marginal advantage makes it not worth it, and said already that literate programming does things that conventional doesn't.
(If you don't know what a marginal advantage is, you may want to poke around on the internet a bit. It's a very valuable concept. And I see a lot of people using the word in a way that shows they don't really know what it means; it is commonly thought that it means something "small" or "insignificant". That's not what it means.)
"There is nothing to tell you this information in a typical program."
This is true, but it's not true because nobody uses strict Knuthian literate programming, it's because nobody is writing those. Languages generally do have a place to put a top-level summary and organize all the rest of the documentation. I know; I use them and write them. All my major systems have an official "top level" location, and generally I put it in the local system's language-specific documentation format (godoc for most of my systems). People just don't write them. Handing them better tools won't solve that problem.
But what's the purpose of divorcing code execution order from the machine, and instead tying that to prose? It's simply to facilitate the reader's understanding of the logical structure of the program without the superficial parts.
Just because you do discuss those superficial features with the "literate-programming as code comments" paradigm doesn't make the program less literate, it just means the prose has to be less efficient.
I do agree it's better to use a system like org-mode for literate programming because it is better to separate the description from its execution, but I'd argue it isn't really the essential element of literate programming.
I completely agree. You can present the material in reader order, not program order.
Literate Programming as conceived by codemonkey-zeta is as described above.
Also, difficulty writing a clear, concise comment is a strong code smell indicating that you don’t sufficiently understand the following block of code. Much better to realise this at the comment stage than at the debugging stage.
Yes! Rewrite that comment until it's sound! Being able to write in spoken language what the code is doing is so often related to the writer's ability to write that code succinctly.
But comments that describe a paragraph/block of code have a separate value. Being able to skim code faster because of a series of well chosen sentences is an aide beyond clear code. As the OP described it is a good way to design before the code is written.
Comments about why something is happening are in my experience much more useful.
An example:
# Using an if / elif rather than a select here
Rather than:
# Use a large if / elif statement here due to a regression in TCL 8.4 which made select statements significantly slower. See GitHub.com/tcl-bugs.
def write_report():
db = connect_to_database()
data = get_data(db)
summary = summarise_data(data)
save_report(summary)
After this, do the same for each of these functions.Verbs in Javaland are responsible for all the work, but as they are held in contempt by all, no Verb is ever permitted to wander about freely. If a Verb is to be seen in public at all, it must be escorted at all times by a Noun.
http://steve-yegge.blogspot.com/2006/03/execution-in-kingdom...
Especially in Haskell where you can stub those functions as undefined and get type checking along the way.
<cycle through params and start a service for each one>
…
<set up an ocr subprocess and handle errors>
…
if (<is a numeric string>) {
<trim whitespace>
<extract integer part>
<send it to /path/to/route>
}
expands into a corresponding full-page code and more details when you click on these parts. Can’t simulate fonts and colors on HN, sorry. This isn’t exactly literate programming, but more like a programming markdown. I wish it was every language’s way to go. I know you can simulate that with functions and IDE, but having a continuous context has its own benefits (you don’t have to pass it around, which is tedious and again technical), and also naming things properly and in a unique non-polluting way is hard.readingCode likeThisKind reallySeemsTo absolutelyDdosMyBrain especiallyAsTheNamesGetLonger.
This is the stuff that a software engineering professor will tell you to do, you ignore it for years, and then later on, after you’ve matured, you find yourself picking up again because it’s just one of those incredibly simple and responsible ways to break down complex problems.
Then I might start sketching the implementation with function signatures docs, types, loops and calls, and gradually start filling it in beginning with the parts that are less clear to me.
I program the same way and wish more people would consider the audience when writing code.
So things like a quick "let's improve this part later, but this is fine for now" become items that are highlighted as not "DONE" and then are seen as eyesores or unprioritized tickets, which leaves a bad feeling for devs.
While I think these features of automatically tracking TODOs can have their uses, like most things if they become metrics they start to lose their value. Sometimes it's better to just have a keyword you can easily grep for when you do find some time, having these results show up as cases against your abilities to finish the work is unhelpful, but that's what the manager and maybe coworkers see, unfortunately.
I believe (but I'm not sure) I do get what you re trying to say, but not every TODO reflects some eternal trade-off. Some are for real clear improvements (like the "there isn't any code here" into "the code was written" on my example) whose history won't add any value after they got done.
On larger teams the likelihood than comments get out of date is probably higher - particularly if the original comment was very long and detailed and the original author has moved on.
Funnily enough, most of the outdated comments I can remember were dead docs links despite that being a very common 'solution' to the problem of outdated comments.
All this is doubly important when designing an API, where the comment (also) serves as the externally visible documentation for that API. It helps me put myself into the shoes of the caller reading that documentation without knowing the implementation details, which I believe helps me design a better API.
I hear that “comments go out of date” a lot, but in my case, if a comment doesn’t match the code, it’s usually the code that needs fixing.