
Whither literate programming: what went wrong? - fanf2
https://medium.com/@torazaburo/whither-literate-programming-2-what-went-wrong-e4a3d89af644
======
daly
It 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
I 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

------
daly
Literate 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
Modern 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
I 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
Test-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
Tooling

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
Agility

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
The 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
IDEs

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
Literate 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
A 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
Speed 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?

