4 ms·
Whither literate programming: what went wrong?
- daly 7y agoIt solves problems that don't need to be solved anymore. "Some critics of literate programming say that modern programming environments no longer have these kinds of issues." Have you tried understanding and maintaining a program built on an IDE that no longer exists? Microsoft introduced an IDE that built windows code automatically, instantly generating about 10,000 lines of code to put up a "Hello, World" window. That generator is gone and the 10,000 lines are all that is left. "Modern Programming Environments" won't run in another 10 years. Github, Sourceforge, and Savannah have 10s of thousands of programs that nobody even bothers to look at because there aren't even a hint about the code.
- daly 7y agoLiterate programming is too much work and/or not necessary I write literate programs all the time. I write in Latex and use a Makefile. THe Makefile compiles the source and rebuilds the PDF. My PDF reader refreshes automatically and I can see my words as well as my code. People seem to think that coding involves a lot of typing and little thought. I find that writing an explanation about code I just wrote helps me think "in the large" about how the code will fit in, and "in the small" about what arguments and results make sense. Oh, and as a side-effect, I have a record of my thoughts I can share with others (aka communication).
- daly 7y agoI don’t need no stinking comments Literate programs are not comments. Literate programming is no "documenting". Literate programming is communicating ideas and details to other humans. A physics textbook is not "documenting physics". Cut out all the equations in a physics textbook. PUt them on index cards. Throw away the textbook. Now try to learn physics "from the code". Confusing literate programming with "comments" and "documentation" is a clear indication of a lack of understanding about what it means to communicate.
- daly 7y agoIDEs An IDE is a tool. Tools make tasks easier for the person using the tool. But the tools needed to build a program have nothing to do with what the program does and why it does it. I have a whole workshop of tools to work on cars. The tools tell me nothing about what a car does and why it does it. I'd hardly want to teach people to drive by insisting they use my tool cabinet.
- daly 7y agoTooling To extract source code from latex requires a 170 line C program. It runs in less than a microsecond. A simple Makefile stanza looks like all: pdflatex file.tex tangle file.tex >file.c gcc -o file file.c and, by magic, my PDF ivewer updates with the latest file changes, source and/or code. And, by magic, I have a running program. And all I had to do was type 'make'
- daly 7y agoLiterate revision management Ummm, seriously? You don't put a changelog in a literate program. That's what git is for. Just like your driving instructor doesn't teach you about cars by reading the mechanics comments... changed right front brake. changed the oil. You're making a "category error".
- daly 7y agoModern features in programming languages I love the thought that we're "modern". But we still use the pile-of-sand (POS) style of organization, putting semantics is directory names (e.g. src, inc, lib, and the always empty "doc" directory). And then we REALLY communicate all the semantics you needs with filenames... like parser.c SINTECX.ml or DONR.xlp Books have built-in semantics. You know chapters, sections, paragraphs, table of contents, index, table of equations, figures, images, etc. And now PDFs can hyperlink both internally and externally. Organize your code the way you organize your thoughts.
- daly 7y agoTest-Driven Development "Literate programming has never provided a convincing story about how it would co-exist with today’s test-centric priorities." What nonsense. You can inline tests as well as code (which I do) and you can have an appendix (or multiple) that contains whole categories of tests. In fact, test cases are excellent for explaining how a function is expected to be called and show cases where it will fail.
- daly 7y agoSpeed of change What? You can add spiffy new features to your code so quickly that you can't even explain that they are there, let alone how to use them?
- daly 7y agoAgility When you check in a piece of code, it should NOT pass code review without at least a paragraph or two about why this code exists and what it is intended to do. It makes no sense to drag 6 people into a code review without them knowing this information. So write it down. Magically, one could extract all of those paragraphs and their code into a literate program. You want quality? THIS is how you get quality.
- daly 7y agoThe demise of program design The argument is that programmers immediately start coding. I've worked in many shops that developed products. Nobody does that. You can't code what you don't understand. After all, you have to "explain" what you want to the computer which is MUCH harder than explaining why you want it to a human.
- daly 7y agoA modular world "A successful, modern incarnation of literate programming is going to have to fully support our current module-based world." Have you heard of "Volumes"? That is, multiple, self-contained books?
- daly 7y agoI practice what I preach. Axiom is a 1.2 million line computer algebra program, in literate programming form. Look at: https://en.wikipedia.org/wiki/Axiom_(computer_algebra_system) https://en.wikipedia.org/wiki/Axiom_(computer_algebra_system... And, if you want to see a "gold standard" example of literate programming see Physically Based Rendering (https://www.pbrt.org/ https://www.pbrt.org/) which won an Academy Award) This book has deservedly won an Academy Award. I believe it should also be nominated for a Pulitzer Prize — Donald Knuth