
Response to “Literate programming considered harmful” - speckz
http://johnwshipman.blogspot.com/2016/02/is-literate-programming-harmful.html
======
quantumhobbit
The trend in programming lately seems to be less to no comments and less to no
documentation; and it is killing the joy I take in programming. Without
comments the only way the next guy has a chance to understand the code is if
you stick to lowest common denominator patterns and frameworks. You can't do
anything that hasn't been done before.

I think this is related to the proliferation of frameworks. I can't come up
with my own pattern that best fits the problem, but I can select from a list
of pre-approved patterns in our framework and shoehorn the problem into it. We
only hire people familiar with the framework, so no need to document.

It really comes down to laziness. A literate program demands you put forth the
effort to understand it and read the docs and code. Whereas a with a framework
program you can copy and paste code from blog posts and stack overflow without
any clue what is really going on.

~~~
nothrabannosir
_> I can't come up with my own pattern that best fits the problem, but I can
select from a list of pre-approved patterns in our framework and shoehorn the
problem into it._

Generally only true for burger flipping software. If your problem is unique,
there won't be a framework for it.

Want to be creative? Try seeking out creative problems.

Everything has exceptions, but this rule of thumb seems to apply well, in my
experience.

~~~
bunderbunder
If your problem is unique and requires creative solutions, and you work in an
anti-documentation team, that's when things get truly nasty.

~~~
qznc
Elsewhere known as "Academia" ;)

~~~
Chris2048
Which also can create documentation without code :-)

------
gavinpc
I recently ran across this piece, "Literate programming: Knuth is doing it
wrong", whose author contends that

> the ends are insufficiently ambitious by focusing on a passive
> representation [0]

After practicing literate programming seriously for over a year on a large
project, I believe that our notion of _documents themselves_ is insufficiently
ambitious, for the same reason.

Computer-based media should not be limited to the static forms imposed by
paper. It's unfair to critique literate programming _per se_ until we have a
truly dynamic mode of representation. ( _edit_ , yes, technically we have that
now, but it's an order of magnitude more work to create. I'm saying that live,
dynamic representations should be our tool for thinking, building, and writing
about things in the _first place_ , not after the fact.)

[0] [http://akkartik.name/post/literate-
programming](http://akkartik.name/post/literate-programming)

~~~
Jtsummers
What tools did you use for this?

~~~
gavinpc
How long do you have?

This was for a project called "willshake." The system provides a rough
overview of itself [0].

I was using Org for documentation, and I decided to try migrating to a
literate codebase.

It was clear immediately that I needed a "real" build tool. After some
research, I decided that was Tup [1]. Tup is a strict, "functional reactive"
build system with extremely fast incremental builds.

So I run the Tup monitor, and everything gets tangled as I write. Great.

But tangling through Emacs/Org was way too slow. So I wrote my own gawk-based
tangle [2] that supports the subset of Org Babel's features that I needed, but
would tangle any file in 20-50ms.

But usually I want to _do something_ with the tangled code (you know, compile
it, run it). So I also define _build rules_ inside of the documents (for
example, [3]). I just extract the rules from the documents and feed them to
Tup.

Now I can just write _whatever I want_ in a document, and stuff just happens
as I write. This includes the removal of obsoleted build targets, which Tup
handles. So I can "literally" remove a document file from the project and the
feature is removed; return it, and the feature is restored.

But as the system grew, the build started to push 2 seconds. This is because
Tup was reviewing thousands of rules whenever any file changed. So I decided
(following Christopher Alexander), to treat _directories_ of documents as
isolated _subsystems_.[4]

So I can create features and subsystems with continuous builds ~250ms, using
only Org files and directories.

It still sucks. I'm taking a detour to explore dynamic documents, which I
think precedes considerations about "programming."

[0] [https://willshake.net/about#more-about](https://willshake.net/about#more-
about)

[1] [http://gittup.org/tup/](http://gittup.org/tup/)

[2]
[https://bitbucket.org/gavinpc/willshake/src/default/bootstra...](https://bitbucket.org/gavinpc/willshake/src/default/bootstrap/tangle)

[3]
[https://willshake.net/about/the_stylesheets#sec-4](https://willshake.net/about/the_stylesheets#sec-4)

[4]
[https://bitbucket.org/gavinpc/willshake/src/default/bootstra...](https://bitbucket.org/gavinpc/willshake/src/default/bootstrap/rules.lua)

~~~
Jtsummers
Finally had a chance to review your various links. That's a very impressive
project, I like it quite a bit and have now shared your product
(willshake.net) with several friends.

Thanks for the links and the resources. My target with literate programming is
a bit different than yours, but you've given me some things to think about. I
appreciate that.

~~~
gavinpc
Thanks, it makes my day to hear that. I think literate programming was ahead
of its time in some ways, including ways that maybe Knuth didn't anticipate.
Good luck.

------
lumpio-
Even if it was "harmful" it wouldn't be such a big deal because I for one have
never seen an actual program written in literate programming style.

~~~
lokedhs
You're in luck. TeX is written in literate style, and its documentation/source
is available here: [http://brokestream.com/tex-
web.html](http://brokestream.com/tex-web.html)

You can also read Knuths description of the Web system he under to write the
code here:
[http://www.literateprogramming.com/knuthweb.pdf](http://www.literateprogramming.com/knuthweb.pdf)

------
falcolas
I feel bad to say this, but the practical world has burned me so many times
that I simply can't trust anything said after a comment delimiter. If it's not
in the code, it doesn't have any impact on what the code is actually doing,
making it redundant at best, and misleading at worst.

For that reason, I find myself constantly reverse engineering code. If I am
tracking down a bug and run across a bit of obfuscated code which has the
comment "optimized hotspot sorting", I'm going to assume that it's wrong. I'm
going to take the time to reverse engineer that obfuscated code, to make sure
that the code is actually sorting, that it it an actual hotspot, and that it's
not the cause of the bug I'm chasing down.

I guess I use it as a negative signal: "the comment says the code does X, I
need to verify that it actually does X, correctly". "Optimized" code blocks
and comments taken as the truth have pointed me at more bad code than good
code.

------
andy_ppp
My new checklist for making programs easy to understand and work with in the
future.

\- Make the program in complete slices of a functionality and put those into
folders and files that are descriptive of what the code does:
"web/login/facebook/always_ask_for_email.lang"

\- Do repeat yourself in different functionality areas.

\- Name your variables and functions as if they should never conflict/as
specifically as you dare.

\- Use a functional and immutable programming language or write pure functions
as much as possible.

\- Stop thinking that patterns are necessary to solve the problem of turning
data from one form into another.

I might be wrong.

------
kozikow
I use literate programming for "research" projects - I use emacs org mode with
org babel and ob-ipython. It is useful for that purpose, as I am usually
chasing a few options in parallel and results later will need to be presented
to the team.

When project wasn't that researchy in the first place (does not require
significant experimentation to come up with the solution), or exits the
research phase I move to standard programming tools.

------
wodenokoto
I definitely find literate programming intriguing.

I like stuff that's well documented and I find my own documentation crucial
for understanding things.

I am however a bit at a loss about the practicalities.

Does writing a doc-string for each class/method/function and connecting to
readthedocs count as literate programming?

~~~
js8
"Does writing a doc-string for each class/method/function and connecting to
readthedocs count as literate programming?"

I don't think so. It's like comparing the Lord of the Rings, the novel, with
the index that contains descriptions of all the characters in the Middle
Earth.

I mean both tell you the same story, but from a very different perspective.

I am personally not a fan of (what I understand as) literate programming,
_unless_ you are writing a piece of educational code that is supposed to be
read from beginning to end (like Jones Forth, for example).

What I think should be done instead, the code should be documented on several
levels, each level more detailed by a constant factor. So each couple lines
should have a comment, each function should have a comment what it does with
what parameters, each class (or group of functions) should have a description
of their purpose, each module should have a description of its architecture
and interactions, and so on until you would get to the top level architecture.
So it would be more like a tree of more and more detailed documentation rather
than linear novel that you read from start to end.

------
snaky
Literate DevOps (with Emacs, Org-Mode, Tramp) -
[https://www.youtube.com/watch?v=dljNabciEGg](https://www.youtube.com/watch?v=dljNabciEGg)

------
jfe
The value of literate programming is proportional to the novelty of the
material it documents.

------
jayeshbadwaik
You don't say....

------
Apaze
Is <insert whatever type of language /> programming harmful?

What question is that?! If you write malware with it, yes it is! Though not
for you.

~~~
lucozade
They're just using a headline derived from Dijkstra's "Go To Statement
Considered Harmful". As with Dijkstra it's a bit clickbaity i.e. they really
mean use with care rather than harmful.

Making it a question just gives the extra benefit of making it likely to
conform to Betteridge's law. So a meme win-win really.

~~~
cwyers
Of course, Dijkstra wasn't really clickbaiting, as clicks hadn't been invented
yet.

