
Code is not literature (2014) - setra
http://www.gigamonkeys.com/code-reading/
======
daly
Code is not literature the same way equations are not mathematics. Take any
math or physics book, extract all of the equations, and throw away the text.
That's how we write programs... just the equations.

However, look at Physically Based Rendering
([http://www.pbrt.org/](http://www.pbrt.org/)). It won an Academy Award. It
should win a Pulitzer. All of the actual source code is in the book and the
book is quite readable.

Or look at Lisp in Small Pieces
([https://pages.lip6.fr/Christian.Queinnec/WWW/LiSP.html](https://pages.lip6.fr/Christian.Queinnec/WWW/LiSP.html)).
There you will find a complete lisp system surrounded by enlightening text.

Your confusion stems from the coding constraints of the 1970s. My first
machine had 8k of memory, 4k of which was operating system. So programs could
not exceed 4k, requiring #include statements. As programs grew they adopt the
"pile of sand" (POS) format where the "meaningful" directory names like 'src',
'doc', 'test', etc contain the semantic content.

Of course nobody reads POS code. It wasn't written to communicate to humans.

It's the late 90s... code like humans matter, like your code needs to be
understood, maintained, and modified. Write literate programs similar to
Physically Based Rendering and Lisp in Small Pieces. Stop programming like
your grandfather did. Oh, yeah, and write provable programs... but that's
another rant.

~~~
glangdale
I am rather conflicted to read this advice. I think we all _want_ to do this;
on the other hand, I think we also generally cannot afford the time to do it.
In the project that I run, many major subsystems have been obsoleted by other
algorithms, changes in the underlying hardware, etc. Every hour spent not
writing beautiful literate code to communicate with other humans in these
cases is an hour saved.

And yet, and yet.

~~~
white-flame
Every hour saved in skipping code readability is 4 hours wasted later in
trying to reverse engineer what the code author was doing. Discarding on-the-
job code with no maintenance or bug-fixing is astonishingly rare. Even
building different parts of a system often requires some code updates in other
portions, even if it's not even executed yet.

Also, writing your thoughts into concrete, descriptive comments helps you with
rubber-duck debugging, often pointing out weaknesses or edge cases you didn't
think of when you were heads-down in the code. It's far faster to fix issues
that come up ahead of time than after you've swapped it out of mind.

~~~
otikik
I have been that second person many times and I agree completely with this
comment. When you skip readability you are saving your own dev time at the
expense of other future devs'.

~~~
sqeaky
That sounds like _debt_ in time against the _technical_ aspects of the system
in question.

If only we as an industry had some label for this _Technical Debt_ so that we
could appeal to practices like refactoring, unit tests and continuous
integration to pay it down.

~~~
vorg
All business is about borrowing stuff from the future -- getting as much gain
as possible now and deferring the costs as far as possible into the future,
when someone else needs to pay back the debt, or when it can be defaulted on.
Business managers don't let tech workers spend time refactoring because it
violates this basic business principle. They will make up some other positive-
sounding label, e.g. _Agile Development_ , and bandy that around instead. When
the system's technical debt is called in, those managers will have already
moved to another system to pull the same con, or they'll replace the system
with a fresh one complete with green-card-seeking programmers. The programmers
on the old system will be retrenched without payment via stack-ranking, and
their health problems caused from stress and lack of sleep forgotten about.

------
mpweiher
There's a distinction I've noticed ever since university CS:

The code-starers and the experimentalists. When debugging, the code-starers
would, well, stare at the code and try to reason this out logically. There
will be statements such as "this cannot be the case, because ...".

The experimentalists would _run_ the program with variations in input and code
and observe the effects in order to figure out what was _really_ happening.

As you can probably tell, I am an experimentalist, and I find the code-staring
approach puzzling: (a) the world is not as you expect it to be, so reasoning
about what can or cannot be the case is of limited use, as your reasoning is
evidently faulty (usually assumptions). (b) there is a real world you can ask
questions, why would you not want real answers??

Philosophically and historically, I consider the move towards empirical
science (Bacon etc.) probably the greatest advancement humanity has made to
date. It certainly is dramatically more effective than any other method of
separating truth from non-truth we have, whereas scholasticism...

~~~
TeMPOraL
I'm a "code starer" that uses experiments to inform the "staring" phase. I
look hard at the code, think to myself "this can't happen... unless", I
formulate the hypothesis and then use experiments to prove/disprove it.

While the shotgun approach to science (run random experiments and see what
correlations fall out) can be useful at times, there's a benefit to figuring
out precisely what you're looking for before you start looking.

~~~
mpweiher
> shotgun approach to science...random experiments

Not sure where you get that from someone extolling the empirical scientific
method and science in general.

You obviously don't type random strings until by chance you hit on something.

Scientific method includes cycles of hypothesis, experiment,
validation/refutation.

~~~
mannykannot
If you present your view as a simplistic dichotomy, you should not be
surprised when it is taken as such, and if you put questions in your post, you
should not be surprised if someone answers them.

~~~
mpweiher
The dichotomy was between _experimentalists_ and code-starers. Not between
random-code-typers and code-starers.

~~~
mannykannot
Your characterization of 'code-starers' is a caricature, and the questions you
posed suggested that you did not fully understand the scientific method.
TeMPOral's post was a reasonable response to it.

------
owenversteeg
I think, just like writing, some code is meant to be read but most is produced
as a fact of life. For example, of what I write in my daily life - emails, HN
comments, papers, text messages... the majority aren't meant to be
aesthetically pleasing at all. But occasionally I will write something, either
on purpose or by accident, that's just a little bit poetic and nice. Or I'll
sit down to write a story, or a blog post, or something that's meant to be a
bit nicer to read.

There's a continuum of how nicely things are written in real life: if you just
crashed your car, you might text your family quickly telling them what
happened. Or if the site went down, you might hack together a quick fix.
That'll be utilitarian, since in a situation like that you don't give a damn
about how well the text/code "flows". Then there's writing where you're not
pressured for time, but you don't care about the style: most code people write
is like this. Then finally there's code, and writing, that's intended to be
beautiful. It's written with the intent of showing it to other people, and
with the hope that someone will read it and say "wow".

The reality, however, is that most code - and most writing - is merely
utilitarian. And even when people -do- try to make their code (or writing)
beautiful, they aren't skilled enough to do it. Hell, just because I _want_ to
write like Márquez doesn't mean I can.

There is code that is literature, but it's hard to find. It may be lost,
written on a whiteboard in a job interview to impress the company. It may be
hidden from the world, the author embarrassed by it. Or, it might be out there
somewhere, but nobody's discovered it yet.

~~~
Roboprog
To further extend that idea, you can lump code you (must?) read into 2 broad
overgeneralizations:

* An informative program that you will learn something (good) from.

* A cryptic cipher (seemingly) that will only make your eyes bleed and your head ache.

Just sayin'.

------
ideonexus
Seibel's observation that reading code is less like literature and more like
science is dead on. No matter how readable the code is, when I'm confronted
with 10,000 lines of it spread across numerous encapsulated functions, I must
tackle it very differently from how I read prose. With a complex literary
text, I can just read it in linear fashion with occasional segueing to look up
words and concepts, with well-engineered code I must follow numerous cases
into different flows of logic. These aren't the same at all.

I appreciate that he's trying to dispel the idea that we "read" code as we
read for pleasure, I learn from code by experimenting with it. I open up the
debugger and step through it, watch the variables change and see where it goes
when I execute it. Most of all, I learn by changing that code and trying to
build on it. I have enhanced my javascript skills immensely in recent years by
cloning various projects on github and trying to expand on them or adopt them
to my own purposes. I don't recommend opening up a code base and just reading
it, actively engage it, break it, and enhance it.

------
ryandrake
> Tl;dr: don’t start a code reading group. What you should start instead I’ll
> get to in a moment but first I need to explain how I arrived at my current
> opinion.

Hmm.. Isn't the TL;DR supposed to be for readers who don't have that "moment"
for you to get to the point?

~~~
ljw1001
Blogs are also not literature, apparently. :) Otherwise they would merit more
careful editing.

------
oddlyaromatic
Literature is not an inherent quality, for me. Literature (and art more
broadly) is among other things a lens that humans look at statements and
groups of statements through. There is no "Is this literature?", there is only
"what happens when I treat this 'as literature'"? Is it useful to treat the
complex interconnected statements in a codebase as literature? Yes, probably,
to some people. For me music and plays both provide good structural references
for me learning to code. It is occasionally useful to me to connect these
things. But I also treat literature itself as a bit of a specimen as the
author suggests- I want to know about a poem, what is b it, how does it work,
w why is it this way and not some other way. I want to "run" a poem out loud
and see what the sounds are.

Some of the other comments point out that the literature idea doesn't work for
all code. It probably helps if both the author and the reader buy in to the
idea. But I can't get behind the idea that it's true to say "code isn't
literature" when what seems to be the case is that literature is a thing we
_can do_ to texts, not a thing we _must do_. Code might be a genre of text? I
don't know. But maybe the baby is being thrown out with the bathwater here.

------
suchire
Reading code may not be like reading literature, but I find writing code to be
remarkably similar to writing prose. I wrote about that in more detail here:
[http://www.ericsuh.com/blog/posts/2016/01/writing-
code.html](http://www.ericsuh.com/blog/posts/2016/01/writing-code.html)

~~~
oddlyaromatic
You make good points there, I've proudly omitted so many needless words over
the years.

------
eternalban
Apropos of the Asimov's remarks, I find it rather sad that a literature major
is completely ignoring that _literature can only exist in a cultural context_.

Sans culture, written text is just that: written text, and there can be no
"literature".

And given that literature is 'machine code' for the 'psychological machine' of
the Human 'reader', it should have been clear to OP from day 1 that if there
is such a thing as "software as literature" it must be 'read' from the pov of
Machine, SICP gods' notwithstanding.

[edit]

------
henrik_w
Previous discussion:
[https://news.ycombinator.com/item?id=7091495](https://news.ycombinator.com/item?id=7091495)

------
austincheney
There are two schools of thought on this: it is and it isn't.

For people who believe code isn't literature descriptive names are wasted
characters. The biggest difference between code and literature is that code is
structured where literature isn't (literature makes up for this with a flow
like a plot). Explicit structures are things like subtypes and nested scopes,
qualities that exist directly and not through inference or reference
resolution. There are things that can be inferred directly from structures
like context and scope. For these developers code can be less explicit and
less wordy because they aren't reading code line by line and guessing at how
the pieces come together.

The code is literature camp represents an educated formalism. In the absence
of explicit structures you need to understand what the code is doing by simply
reading the code.

The problem with the code is literature approach is that it is for humans
only. The computer absolutely doesn't care, and so therefore it can be wrong
or deceptive.

~~~
mtrn
> For people who believe code isn't literature descriptive names are wasted
> characters.

Data point: I do read code like books and I can't stand longAndMeaningful
variable names. Rather, cut to the chase.

~~~
TheOtherHobbes
The chase being what?

It takes no time at all to read a longAndMeaningful variable name, and no time
at all to work out what it's doing.

Assuming you don't name variables a1 to z256, calling a variable something
like "items" makes it context dependent, which is a little too much like
building state into the syntax.

Long names provide an extra informal level of type safety. You should be able
to see what a variable is doing by looking at it, and you should also be able
to see that it provides a clean level of abstraction/composition instead of
just being an arbitrary container with a label.

~~~
Vinnl
I think it's somewhat of a middle ground. What I think hampers your ability to
understand code, next to not knowing what variable names are supposed to mean,
is not being able to easily discern variables from eachother, making you do
double-takes while reading and thus making it more difficult to understand. If
your code is littered with variables like longAndMeaningful and
longAndWithMeaning and lengthyAndMeaningful etc, that becomes really annoying
to read.

And of course, there's a difference between longAndMeaninful and
reallyVeryLongWindedAndExplicitButOhSoMeaninful. And let's not start about the
FactoryFactoryBuilderEtc thingies.

------
pards
>> in order to grok it I have to essentially rewrite it

That whole paragraph describes exactly how I go about learning sections of a
new codebase.

Rename stuff, pull out methods and classes, reformat etc until I have a few
"a-ha" moments then I discard my changes and re-read the original with a
little more enlightenment.

------
ljw1001
The author is looking at this from the perspective of someone who reads 'for
fun' or generalized learning. When you have to maintain (or god forbid,
rewrite) a module, you do a lot of code reading. At that point the more like
reading a good essay it is, the better.

~~~
ljw1001
I would take it one step further and say that a better analogy than collecting
specimens would be that code-reading is like doing secondary research: Read an
overview, dive down one path, take notes, find and read three more articles,
etc.

------
streambranch
What came to my mind while reading this is code is closer to poetry than it is
to 'literature'. Not a perfect analogy mind you but it shares these qualities:
\- It tends to be dense. \- It is meant to be decoded. \- The
terms/words/commands/formatting are picked carefully to evoke concepts (and in
poetry, feelings).

This reminds me of something a friend said to me a long time ago about his
lack of interest in crosswords: "If I want a good puzzle I read a poem."

I've always approached other people's code as a puzzle.

------
quickoats
literature feels also a lot like decoding science specimens, in the same sense
in the article as to get at or understand the author's mind; i feel that code
and 'literature' are the same. the reader of code plays the part of the
compiler, computer, or conveyor. the reader of prose literature plays the part
of spectator, character, or anything. these words too, is also code for our
human computers to syntax-check and preprocess and accept/install or
discard/patch.

------
xyzzy4
Reading code is more like figuring out all the plumbing of a large building.

