3 ms·

I would go so far as to say it is literate programming. People tend to think literate programs require an extensive system to support them, such as org-modes's

I would go so far as to say it is literate programming. People tend to think literate programs require an extensive system to support them, such as org-modes's emacs integration, or weird meta-programming facilities, but the truth is a program written in any language that support comments can be literate programs, so long as the content of the comments dominates and dictates the structure of the code -- which is exactly what GP commenter's method sounds like.

sicp-enjoyer 4y ago
> so long as the content of the comments dominates and dictates the structure of the code 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.
- TheSpiceIsLife 4y ago
  As conceived by Donald Knuth. Literate Programming as conceived by codemonkey-zeta is as described above.
- codemonkey-zeta 4y ago
  > The key feature of literate programming is separating the order that code is written in from the order that the compiler requires 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.
  - sicp-enjoyer 4y ago
    > It's simply to facilitate the reader's understanding of the logical structure I completely agree. You can present the material in reader order, not program order.
- jerf 4y ago
  "The key feature of literate programming is separating the order that code is written in from the order that the compiler requires"... in the languages that were popular at the time Knuth wrote the definition, which were very rigid and uncompromising on layout. 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.
  - sicp-enjoyer 4y ago
    You are certainly correct that older languages had more constraints on ordering, but I completely disagree that modern languages have removed all restrictions. I assume in whatever language you are imagining you have things like methods in classes or namespaces. This forces you to write them all together. The ability to separate those out is powerful. 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.

sicp-enjoyer 4y ago

> so long as the content of the comments dominates and dictates the structure of the code 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.

TheSpiceIsLife 4y ago
As conceived by Donald Knuth. Literate Programming as conceived by codemonkey-zeta is as described above.
codemonkey-zeta 4y ago
> The key feature of literate programming is separating the order that code is written in from the order that the compiler requires 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.
- sicp-enjoyer 4y ago
  > It's simply to facilitate the reader's understanding of the logical structure I completely agree. You can present the material in reader order, not program order.
jerf 4y ago
"The key feature of literate programming is separating the order that code is written in from the order that the compiler requires"... in the languages that were popular at the time Knuth wrote the definition, which were very rigid and uncompromising on layout. 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.
- sicp-enjoyer 4y ago
  You are certainly correct that older languages had more constraints on ordering, but I completely disagree that modern languages have removed all restrictions. I assume in whatever language you are imagining you have things like methods in classes or namespaces. This forces you to write them all together. The ability to separate those out is powerful. 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.