This is the
talk page for discussing improvements to the
Literate programming article. This is not a forum for general discussion of the article's subject. |
Article policies
|
Find sources: Google ( books · news · scholar · free images · WP refs) · FENS · JSTOR · TWL |
Archives: 1 |
![]() | This article is rated C-class on Wikipedia's
content assessment scale. It is of interest to the following WikiProjects: | |||||||||||||||||||||||
|
|
|
This article is or was the subject of a Wiki Education Foundation-supported course assignment. Further details are available
on the course page. Student editor(s):
User:Pranavnawathe.
Above undated message substituted from Template:Dashboard.wikiedu.org assignment by PrimeBOT ( talk) 02:43, 17 January 2022 (UTC)
As noticed by 206.47.249.252, the source code listed is not quite C, as promised to the syntax highlighter. It's unlikely the highlighter will ever support something like lang="noweb#c", so it may be best to just use "<pre>" or custom formatting instead. But the former looks plain and the latter is labor intensive... — Preceding unsigned comment added by Daggerbox ( talk • contribs) 02:20, 7 January 2011 (UTC)
The article would be improved if it contained a list of software programs that have been written in a literate programming style. From what I gather, this is still a small number, so a list would not be out of place. I know of TeX (which was even published as a book TeX: The Program) and METAFONT by Knuth, and I've heard about Axiom, but are there any ("big") programs or software projects written in literate programming? 59.92.198.129 ( talk) 07:32, 22 March 2011 (UTC)
I. Actually, if we include Notebook interfaces, which wikipedia also classifies as LP tools, LP is used a lot- right from the deployment of Mathematica notebooks on the Apple II.
II. It has not been clearly stated, but Tim Daly's "Axiom" does not just provide LP tools, but is a massive CAS, created completely with LP.
III. "Physically Based Rendering"- the great literate program which was used to create slick CGI software, with the documentation published as a textbook, is a great example- and it's use by Pixar earned its makers an Academy Award.
IV. More examples in the lecture by DEK:
https://channel9.msdn.com/Events/useR-international-R-User-conference/useR2016/Literate-Programming
-PSG1997 — Preceding
unsigned comment added by
PSG1997 (
talk •
contribs)
19:40, 7 December 2018 (UTC)
Literate programming is almost a standard approach in scientific computing decades and now in data science too. -- mcyp ( talk) 02:09, 30 May 2020 (UTC)
Nothing here to make clear what action to take in nearly a year so removed. Please replace if you can give specfics. 72.228.189.184 ( talk) 15:21, 6 May 2012 (UTC)
I updated external references but tried to include external links in my revision comment. Guess what: It didn't work!
This is what my edit was: I revised URLs due to the transition of EHC content to UHC per the UHC Wiki Project News, (Sept 2010). I also removed red link/ non-existent wikilinks. Also, I updated and cited properly, the Web68 reference. -- FeralOink ( talk) 14:41, 1 January 2013 (UTC)
Project Jupyter should probably be added to the list of examples.
Best wishes. RobbieIanMorrison ( talk) 22:50, 21 November 2016 (UTC)
This section is initiated by someone suspected of vandalism. -- mcyp ( talk) 02:09, 30 May 2020 (UTC)
![]() | The
neutrality of this section is
disputed. |
The article is totally missing any discussion of the failings and shortfalls of WEB or even Literate Programming as concept. Instead it reads as The Gospel according to Saint Knuth. The fact that even proponents of this abortive concept struggle to find examples of relevant software written in it (other than by Knuth himself) should alert to the many reasons that make it next to useless for any proper software project outside of the software lab of Knuth & His Acolytes. Allow me to mention a few: Substituting 'natural language' for properly defined programming languages can only lead to increased ambiguity, not less; proficient programmers should have no difficulty conveying (and understanding) meaning through properly written code in a well-known programming language; this is especially true for the most complex parts of algorithms (ie, where it matters most), and even the WEB examples provided for Unix's 'wc' program (a relatively simple application) amount to a load of comments around blocks of traditional code that carry out the actual work; ie, it increases verbosity ungainfully.
I should probably work these objections into the article myself, but i can't be bothered. If this Literate Programming nonsense mattered to anyone other than Knuth's uncritical followers, the article would already have plenty mention of these issues, and others. (By the way, this Knuth fellow is the guy who, not so long ago, lambasted the hell out of microprocessor designers for 'persisting' in making multicore architectures, claiming that it is incumbent upon them to build fast single-threaded processors instead of trying to 'force' programmers to learn parallel programming. WTF?) — Preceding unsigned comment added by 79.168.138.50 ( talk) 20:52, 12 January 2017 (UTC)
While I agree that LP has serious flaws, your comments seem to indicate that you have entirely missed the point. It is in mo way a 'natural language programming' attempt, and the fact that you seem to think it is shows that you haven't read the explanation carefully.
The goal with LP is code documentation (as differentiated from either code comments or the code itself), a practice that is generally ignored in the industry at large. While the typical LP system such as noweb involves the writing of the code and documentation together, the intent is not that they be read together; rather, the LP document is processed into separate source code ('tangling') and prose documentation ('weaving') files. The crux of the idea is to ensure that the documentation remains in sync with the source code. The intention - flawed though it is - is to have a document the programmer can read before looking into the code proper.
The problem, of course, is that hardly any real-world programs have any code documentation at all, for reasons completely unrelated to the technical merits or flaws in the idea. The real reason LP fails is because managers don't care about code documentation (or code maintenance in general), and trying to write any would be career suicide for a working programmer. This is the sad, idiotic reality of the IT industry, and is unlikely to change any time soon.
I do think the idea has more merit than it is usually credited, but I do not consider the approach as given by Knuth to be adequate - what it really calls for is a hypertextual approach, and one not tied to using inline markup as seen in HTML, at that. However, even that won't ever get most programmers to adopt it, because it runs counter to the running-in-place nature of the industry at large. It is yet another sign of how programming as a field is Lewis Carroll's Red Queen - it runs at full speed without advancing, always moving but going nowhere new despite the appearance of change. All the advancements of the past four decades have been down to hardware - the software, while radically different than in the past, is not actually innovative. The last truly new things in the field were the LZ compression algorithms and the Bricklin spreadsheet model - both of which date to 1977. The rest is just rehashing things that were too hardware-intensive to be practical before. Schol-R-LEA ( talk) 18:48, 17 March 2018 (UTC)
Haskell is a very formal language, it supports algebraic data types and is a purely declarative language. A programmer use algebraic laws to transform code into a more efficient equivalent one. For that reason I rewrote that point. — Preceding unsigned comment added by 189.233.107.221 ( talk) 22:23, 28 March 2017 (UTC)
I am not sure that you have actually understood the idea or intent of LP. The key idea is not to try to write 'self-documenting' code, but to write the prose documentation for the code (which is a separate concept from both code comments and code clarity - and one almost always ignored in practice) together with the code itself, with the tangle and weave tools then separating them for alternate presentations. The goal is to ensure that the code documentation - which, as I already said, is not widely practiced in the first place - is updated at the same time as the code. The source code itself is automatically extracted from the LP document once it is written - the LP document is not itself source code.
While the idea is sound when approached in a vacuum, in practice it has serious problems, primarily in that, like Test-Driven Development, in it's classic form it is really only suited for example programs - projects which have a clear goal at the outset, where the design does not change during the initial coding process and is never updated afterwards. While the intent was to ensure that the code documentation is synchronized to the source code itself, the assumption that documentation is going to be written at all entirely ignores meat-grinder the reality of commercial code development - if a programmer were to take the sort of time to meticulously document their code in this manner, they would be dismissed out of hand as being unable to keep their schedule.
This is unfortunate, but the primary forces at work are economic ones, not technical ones - good engineering practices in software development are the exception rather than the rule, because the people responsible for deciding the 'best practices' are not themselves software developers, and usually hold programmers in contempt as mere factory laborers. The entire point of things like Agile Development (before they too got corrupted) was to find a way to cope with this reality.
However, the fact that the idea is so poorly understood has made those problems irrelevant - it gets ignored because no one except academics have bother to look at it in the first place. It could well have merit if a way to adjust it to fit the reality were found (unlikely as that is), but the truth is that no one cares enough to try. Schol-R-LEA ( talk) 17:18, 17 March 2018 (UTC)
Hello fellow Wikipedians,
I have just modified one external link on Literate programming. Please take a moment to review my edit. If you have any questions, or need the bot to ignore the links, or the page altogether, please visit this simple FaQ for additional information. I made the following changes:
When you have finished reviewing my changes, you may follow the instructions on the template below to fix any issues with the URLs.
This message was posted before February 2018.
After February 2018, "External links modified" talk page sections are no longer generated or monitored by InternetArchiveBot. No special action is required regarding these talk page notices, other than
regular verification using the archive tool instructions below. Editors
have permission to delete these "External links modified" talk page sections if they want to de-clutter talk pages, but see the
RfC before doing mass systematic removals. This message is updated dynamically through the template {{
source check}}
(last update: 5 June 2024).
Cheers.— InternetArchiveBot ( Report bug) 16:28, 3 January 2018 (UTC)
Just an amplification or clarification of what the existing section says.
Disclaimer: I am neither a Wikipedia editor nor a professional programmer. But this section triggered my memory of reading the McIlroy article many years ago.
McIlroy's wonderful metaphor "industrial-strength Fabergé egg" is a critique of the algorithm Knuth chose for his example, and not at all a critique of Literate Programming (which McIlroy praises). He criticizes the use of a complex algorithm for a problem which has a much simpler solution. And he criticizes the unnecessary use of a complex data structure, but he praises the data structure itself. (He does also criticize some small details of the actual presentation of the algorithm in the Literate Programming example, but not the use of Literate Programming.)
Dudley Brooks ( talk) 18:51, 12 December 2019 (UTC)
Given the context, I'd expect the title of the "Latex" section to make slightly more sense as "LaTeX", but I'm still not sure it's supposed to have anything to do with this TeX format. Can anyone shed some light on the matter? Splibubay ( talk) 21:06, 8 July 2020 (UTC)
Where says:
Should say:
Could the MATLAB Live Script be considered literate programming? Does it matter if the file is a binary format? — Preceding unsigned comment added by 206.241.0.254 ( talk) 20:37, 8 February 2022 (UTC)
It seems that almost all of the entries in the huge table are misleading in that people will read them as examples of literate programming tools. One extremely common example is Jupyter notebooks and its many clones (including things like org-mode), which are systems that are useful, but have nearly nothing to do with the actual proper concept of literate programming. They're usually even more limited than semi-literate programming, since you cannot split code in arbitrary places (eg, function definition in one code block, and its body in a different block).
Removing non-LP tools is likely to be futile since people will probably add such tools again. Instead, it would be better to drop the table completely, and have a quick mention of a few *proper* LP tools. (In the sense that they do unrestricted tangling of code.) — Preceding unsigned comment added by Elibarzilay ( talk • contribs) 12:34, 1 June 2022 (UTC)
References
Jupyter kernels typically allow the code in a cell to be executed without re-executing any preceding code, providing superior interactivity. Codebraid has advantages for projects that are more focused on creating a document than on exploratory programming.
I think like at every other table involving softwares on wikipedia, this table should have licenses too? Yashpalgoyal1304 ( talk) 05:59, 3 December 2022 (UTC)
We have a "Critique" section that appears at first to be (and legitimately should be) about critiques of the idea or general practice of literate programming. Instead, it is a tedious exegesis of an actually incorrect critique of one constructed example someone wrote. This badly misleads the reader into thinking this material is pertinent, wasting their time reading it only to find most of the way through that's it's just been a dirty trick. It's just like one of those jokes that go on for 5 minutes only to have no real punch line (or one suitable for a 5-year-old) just to see if you can get someone to listen to it all and groan at the end.
The material in this part concludes with mention of another test implementation that integrated two different approaches to a solution and that this was in turn the subject of a critique. That critique might conceivably be encyclopedically relevant, but of course it is entirely absent.
Unless someone wants to rewrite this section from scratch to actually be something that belongs in an encyclopedia article on the concept and practice of literate programming, instead of utter trivia about Knuth and McIlroy, this section should simply be removed. — SMcCandlish ☏ ¢ 😼 20:35, 22 June 2024 (UTC)
PS: I see above that this section was previously flagged as problematic for misleading the reader into thinking it was about a critique of LP rather than a critique of an example program. Given that this was posted more than 4 years ago and no improvement has happened in the interim, I'm simply going to remove this pseudo-encyclopedic material. — SMcCandlish ☏ ¢ 😼 20:48, 22 June 2024 (UTC)
This is the
talk page for discussing improvements to the
Literate programming article. This is not a forum for general discussion of the article's subject. |
Article policies
|
Find sources: Google ( books · news · scholar · free images · WP refs) · FENS · JSTOR · TWL |
Archives: 1 |
![]() | This article is rated C-class on Wikipedia's
content assessment scale. It is of interest to the following WikiProjects: | |||||||||||||||||||||||
|
|
|
This article is or was the subject of a Wiki Education Foundation-supported course assignment. Further details are available
on the course page. Student editor(s):
User:Pranavnawathe.
Above undated message substituted from Template:Dashboard.wikiedu.org assignment by PrimeBOT ( talk) 02:43, 17 January 2022 (UTC)
As noticed by 206.47.249.252, the source code listed is not quite C, as promised to the syntax highlighter. It's unlikely the highlighter will ever support something like lang="noweb#c", so it may be best to just use "<pre>" or custom formatting instead. But the former looks plain and the latter is labor intensive... — Preceding unsigned comment added by Daggerbox ( talk • contribs) 02:20, 7 January 2011 (UTC)
The article would be improved if it contained a list of software programs that have been written in a literate programming style. From what I gather, this is still a small number, so a list would not be out of place. I know of TeX (which was even published as a book TeX: The Program) and METAFONT by Knuth, and I've heard about Axiom, but are there any ("big") programs or software projects written in literate programming? 59.92.198.129 ( talk) 07:32, 22 March 2011 (UTC)
I. Actually, if we include Notebook interfaces, which wikipedia also classifies as LP tools, LP is used a lot- right from the deployment of Mathematica notebooks on the Apple II.
II. It has not been clearly stated, but Tim Daly's "Axiom" does not just provide LP tools, but is a massive CAS, created completely with LP.
III. "Physically Based Rendering"- the great literate program which was used to create slick CGI software, with the documentation published as a textbook, is a great example- and it's use by Pixar earned its makers an Academy Award.
IV. More examples in the lecture by DEK:
https://channel9.msdn.com/Events/useR-international-R-User-conference/useR2016/Literate-Programming
-PSG1997 — Preceding
unsigned comment added by
PSG1997 (
talk •
contribs)
19:40, 7 December 2018 (UTC)
Literate programming is almost a standard approach in scientific computing decades and now in data science too. -- mcyp ( talk) 02:09, 30 May 2020 (UTC)
Nothing here to make clear what action to take in nearly a year so removed. Please replace if you can give specfics. 72.228.189.184 ( talk) 15:21, 6 May 2012 (UTC)
I updated external references but tried to include external links in my revision comment. Guess what: It didn't work!
This is what my edit was: I revised URLs due to the transition of EHC content to UHC per the UHC Wiki Project News, (Sept 2010). I also removed red link/ non-existent wikilinks. Also, I updated and cited properly, the Web68 reference. -- FeralOink ( talk) 14:41, 1 January 2013 (UTC)
Project Jupyter should probably be added to the list of examples.
Best wishes. RobbieIanMorrison ( talk) 22:50, 21 November 2016 (UTC)
This section is initiated by someone suspected of vandalism. -- mcyp ( talk) 02:09, 30 May 2020 (UTC)
![]() | The
neutrality of this section is
disputed. |
The article is totally missing any discussion of the failings and shortfalls of WEB or even Literate Programming as concept. Instead it reads as The Gospel according to Saint Knuth. The fact that even proponents of this abortive concept struggle to find examples of relevant software written in it (other than by Knuth himself) should alert to the many reasons that make it next to useless for any proper software project outside of the software lab of Knuth & His Acolytes. Allow me to mention a few: Substituting 'natural language' for properly defined programming languages can only lead to increased ambiguity, not less; proficient programmers should have no difficulty conveying (and understanding) meaning through properly written code in a well-known programming language; this is especially true for the most complex parts of algorithms (ie, where it matters most), and even the WEB examples provided for Unix's 'wc' program (a relatively simple application) amount to a load of comments around blocks of traditional code that carry out the actual work; ie, it increases verbosity ungainfully.
I should probably work these objections into the article myself, but i can't be bothered. If this Literate Programming nonsense mattered to anyone other than Knuth's uncritical followers, the article would already have plenty mention of these issues, and others. (By the way, this Knuth fellow is the guy who, not so long ago, lambasted the hell out of microprocessor designers for 'persisting' in making multicore architectures, claiming that it is incumbent upon them to build fast single-threaded processors instead of trying to 'force' programmers to learn parallel programming. WTF?) — Preceding unsigned comment added by 79.168.138.50 ( talk) 20:52, 12 January 2017 (UTC)
While I agree that LP has serious flaws, your comments seem to indicate that you have entirely missed the point. It is in mo way a 'natural language programming' attempt, and the fact that you seem to think it is shows that you haven't read the explanation carefully.
The goal with LP is code documentation (as differentiated from either code comments or the code itself), a practice that is generally ignored in the industry at large. While the typical LP system such as noweb involves the writing of the code and documentation together, the intent is not that they be read together; rather, the LP document is processed into separate source code ('tangling') and prose documentation ('weaving') files. The crux of the idea is to ensure that the documentation remains in sync with the source code. The intention - flawed though it is - is to have a document the programmer can read before looking into the code proper.
The problem, of course, is that hardly any real-world programs have any code documentation at all, for reasons completely unrelated to the technical merits or flaws in the idea. The real reason LP fails is because managers don't care about code documentation (or code maintenance in general), and trying to write any would be career suicide for a working programmer. This is the sad, idiotic reality of the IT industry, and is unlikely to change any time soon.
I do think the idea has more merit than it is usually credited, but I do not consider the approach as given by Knuth to be adequate - what it really calls for is a hypertextual approach, and one not tied to using inline markup as seen in HTML, at that. However, even that won't ever get most programmers to adopt it, because it runs counter to the running-in-place nature of the industry at large. It is yet another sign of how programming as a field is Lewis Carroll's Red Queen - it runs at full speed without advancing, always moving but going nowhere new despite the appearance of change. All the advancements of the past four decades have been down to hardware - the software, while radically different than in the past, is not actually innovative. The last truly new things in the field were the LZ compression algorithms and the Bricklin spreadsheet model - both of which date to 1977. The rest is just rehashing things that were too hardware-intensive to be practical before. Schol-R-LEA ( talk) 18:48, 17 March 2018 (UTC)
Haskell is a very formal language, it supports algebraic data types and is a purely declarative language. A programmer use algebraic laws to transform code into a more efficient equivalent one. For that reason I rewrote that point. — Preceding unsigned comment added by 189.233.107.221 ( talk) 22:23, 28 March 2017 (UTC)
I am not sure that you have actually understood the idea or intent of LP. The key idea is not to try to write 'self-documenting' code, but to write the prose documentation for the code (which is a separate concept from both code comments and code clarity - and one almost always ignored in practice) together with the code itself, with the tangle and weave tools then separating them for alternate presentations. The goal is to ensure that the code documentation - which, as I already said, is not widely practiced in the first place - is updated at the same time as the code. The source code itself is automatically extracted from the LP document once it is written - the LP document is not itself source code.
While the idea is sound when approached in a vacuum, in practice it has serious problems, primarily in that, like Test-Driven Development, in it's classic form it is really only suited for example programs - projects which have a clear goal at the outset, where the design does not change during the initial coding process and is never updated afterwards. While the intent was to ensure that the code documentation is synchronized to the source code itself, the assumption that documentation is going to be written at all entirely ignores meat-grinder the reality of commercial code development - if a programmer were to take the sort of time to meticulously document their code in this manner, they would be dismissed out of hand as being unable to keep their schedule.
This is unfortunate, but the primary forces at work are economic ones, not technical ones - good engineering practices in software development are the exception rather than the rule, because the people responsible for deciding the 'best practices' are not themselves software developers, and usually hold programmers in contempt as mere factory laborers. The entire point of things like Agile Development (before they too got corrupted) was to find a way to cope with this reality.
However, the fact that the idea is so poorly understood has made those problems irrelevant - it gets ignored because no one except academics have bother to look at it in the first place. It could well have merit if a way to adjust it to fit the reality were found (unlikely as that is), but the truth is that no one cares enough to try. Schol-R-LEA ( talk) 17:18, 17 March 2018 (UTC)
Hello fellow Wikipedians,
I have just modified one external link on Literate programming. Please take a moment to review my edit. If you have any questions, or need the bot to ignore the links, or the page altogether, please visit this simple FaQ for additional information. I made the following changes:
When you have finished reviewing my changes, you may follow the instructions on the template below to fix any issues with the URLs.
This message was posted before February 2018.
After February 2018, "External links modified" talk page sections are no longer generated or monitored by InternetArchiveBot. No special action is required regarding these talk page notices, other than
regular verification using the archive tool instructions below. Editors
have permission to delete these "External links modified" talk page sections if they want to de-clutter talk pages, but see the
RfC before doing mass systematic removals. This message is updated dynamically through the template {{
source check}}
(last update: 5 June 2024).
Cheers.— InternetArchiveBot ( Report bug) 16:28, 3 January 2018 (UTC)
Just an amplification or clarification of what the existing section says.
Disclaimer: I am neither a Wikipedia editor nor a professional programmer. But this section triggered my memory of reading the McIlroy article many years ago.
McIlroy's wonderful metaphor "industrial-strength Fabergé egg" is a critique of the algorithm Knuth chose for his example, and not at all a critique of Literate Programming (which McIlroy praises). He criticizes the use of a complex algorithm for a problem which has a much simpler solution. And he criticizes the unnecessary use of a complex data structure, but he praises the data structure itself. (He does also criticize some small details of the actual presentation of the algorithm in the Literate Programming example, but not the use of Literate Programming.)
Dudley Brooks ( talk) 18:51, 12 December 2019 (UTC)
Given the context, I'd expect the title of the "Latex" section to make slightly more sense as "LaTeX", but I'm still not sure it's supposed to have anything to do with this TeX format. Can anyone shed some light on the matter? Splibubay ( talk) 21:06, 8 July 2020 (UTC)
Where says:
Should say:
Could the MATLAB Live Script be considered literate programming? Does it matter if the file is a binary format? — Preceding unsigned comment added by 206.241.0.254 ( talk) 20:37, 8 February 2022 (UTC)
It seems that almost all of the entries in the huge table are misleading in that people will read them as examples of literate programming tools. One extremely common example is Jupyter notebooks and its many clones (including things like org-mode), which are systems that are useful, but have nearly nothing to do with the actual proper concept of literate programming. They're usually even more limited than semi-literate programming, since you cannot split code in arbitrary places (eg, function definition in one code block, and its body in a different block).
Removing non-LP tools is likely to be futile since people will probably add such tools again. Instead, it would be better to drop the table completely, and have a quick mention of a few *proper* LP tools. (In the sense that they do unrestricted tangling of code.) — Preceding unsigned comment added by Elibarzilay ( talk • contribs) 12:34, 1 June 2022 (UTC)
References
Jupyter kernels typically allow the code in a cell to be executed without re-executing any preceding code, providing superior interactivity. Codebraid has advantages for projects that are more focused on creating a document than on exploratory programming.
I think like at every other table involving softwares on wikipedia, this table should have licenses too? Yashpalgoyal1304 ( talk) 05:59, 3 December 2022 (UTC)
We have a "Critique" section that appears at first to be (and legitimately should be) about critiques of the idea or general practice of literate programming. Instead, it is a tedious exegesis of an actually incorrect critique of one constructed example someone wrote. This badly misleads the reader into thinking this material is pertinent, wasting their time reading it only to find most of the way through that's it's just been a dirty trick. It's just like one of those jokes that go on for 5 minutes only to have no real punch line (or one suitable for a 5-year-old) just to see if you can get someone to listen to it all and groan at the end.
The material in this part concludes with mention of another test implementation that integrated two different approaches to a solution and that this was in turn the subject of a critique. That critique might conceivably be encyclopedically relevant, but of course it is entirely absent.
Unless someone wants to rewrite this section from scratch to actually be something that belongs in an encyclopedia article on the concept and practice of literate programming, instead of utter trivia about Knuth and McIlroy, this section should simply be removed. — SMcCandlish ☏ ¢ 😼 20:35, 22 June 2024 (UTC)
PS: I see above that this section was previously flagged as problematic for misleading the reader into thinking it was about a critique of LP rather than a critique of an example program. Given that this was posted more than 4 years ago and no improvement has happened in the interim, I'm simply going to remove this pseudo-encyclopedic material. — SMcCandlish ☏ ¢ 😼 20:48, 22 June 2024 (UTC)