Slashdot Mirror
Code Is Not Literature
An anonymous reader writes "Hacker and author Peter Seibel has done a lot of work to adopt one of the most widely-accepted practices toward becoming a better programmer: reading high quality code. He's set up code-reading groups and interviewed other programmers to see what code they read. But he's come to learn that the overwhelming majority of programmers don't practice what they preach. Why? He says, 'We don't read code, we decode it. We examine it. A piece of code is not literature; it is a specimen.' He relates an anecdote from Donald Knuth about figuring out a Fortran compiler, and indeed, it reads more like a 'scientific investigation' than the process we refer to as 'reading.' Seibel is now changing his code-reading group to account for this: 'So instead of trying to pick out a piece of code and reading it and then discussing it like a bunch of Comp Lit. grad students, I think a better model is for one of us to play the role of a 19th century naturalist returning from a trip to some exotic island to present to the local scientific society a discussion of the crazy beetles they found.'"
When writing code, your audience is not the compiler.
Your audience is another human being who will be maintaining that code a few years later.
If your audience were the compiler, then your code would just need to compile and run. It could be ugly. Unreadable. Unmaintainable. Uncommented. Have meaningless identifiers. Poor organization. Follow worst practices. Etc. In short, the kind of code you get from an outsourced contractor.
Consider that another human is your audience. Choose identifiers such that a comment is unnecessary. Comments should not say what is obvious. (This assigns foo to x.) Comments should say what is not obvious and cannot be made obvious by the code itself.
Write your code almost as if you are writing literature.
I'll see your senator, and I'll raise you two judges.
By the time some of my literature teachers are done, I'm sure the Hello World would be a subtle and poignant take on the overbearing consumerism as well as taking us to the depths of despair in search of the hero's hidden personality fractures.
The must instructive, enlightening thing I did in college while majoring in CS was to take a part time job grading Pascal assignments for an instructor. Of course my programming experience was significantly above that of the class being taught, but it was still very worthwhile to see how different minds went about solving a specific problem. There were a few students who I could immediately identify (by their code) who had the proper thought process (whether learned or innate - most likely the latter) for software development. I could easily recognize a few groups of 2-3 students who had obviously collaborated on the assignment (it was supposed to be an individual assignment). Students who only knew the most rudimentary constructs of the language were obvious - for example relying on huge sets of if / else statements instead of a simple case statement. There's just something about "reading" and critiquing code that makes you more self aware of the code you produce. Whether we're talking about code efficiency, style, organization or conciseness - I found myself writing better code (again, and not even necessarily through example or having seen something new) after having spent time grading and critiquing others' source code.
Better known as 318230.
It's more about the metatextual narrative. What does this say about the author? This GOTO implies that the author does not want to be where he is. He is desperate to break out; to be anywhere other than where he is now. He's backed himself into this corner, bound in a loop of his own devising, and yet unable to meet the conditions necessary to move forward. "GOTO!" he cries out, "For the love of God, take me away from the endless DO and WHILE!"
Here we see laid out the mind of a soul utterly broken. Can you not feel his burning shame? From the time he first took his toddling steps into the Hello, World! his teachers have admonished him "GOTO statement considered harmful". Yet desperate times call for desperate measures. He casts the thread of his execution into the void*.
Where will he land? We scan the page with increasing alarm. Can you feel your heart quicken? Where is the label? Where are we GOing TO? Now the reader is caught up in the narrative as well as the author. Does the label exist at all? How did this thing ever compile? Until finally, we see it. Safe at last! Our execution can continue, and yet we are forever changed by the experience. Have we exited the loop in the correct condition? Will there be enduring side effects? Read on to find out...
* The void, that is, not a pointer to an unknown type, I just mean to clarify that as a footnote**.
** A footnote, that is, not a pointer to a pointer to a footnote.
It is still a method of communication, though. You can often tell a lot about the programmer and his state of mind at the time by reading his code. It's very easy to tell when they were confused about what they were trying to accomplish, how comfortable they were with the language they were using and whether or not they were in a hurry.
Early on in my career, I started with the assumption that the original programmer knew what he was doing. The more code I read, the more I realized that this is almost never the case. From my observations, it takes about a year for someone to come up to speed with a project, the business process for the company they're working at, and any code base that was already there. Longer if the company's business processes suck. Until then they're mildly to severely confused, and this is reflected in their code. Since a lot of programmers don't hang around at one company for much longer than that, most of the code that I've run across has been crap. The first inclination might be to rewrite it, but as you're starting on a new project you're also mildly to severely confused, so it's best just to study the crap closely and make minor improvements as the opportunities arise. A crap in the hand is worth two in the bush. Or something. Most of the time. I've run across a couple of what had to have been bottom-ten-percent programmers whose crap did end up requiring full rewrites. Coming into a C project where the programmer didn't realize strings are null terminated is a huge warning. C++ or Java code where everything inherits from everything else is also a warning.
I'm trying to teach myself to set people on fire with my mind... Is it hot in here?
Not as much, it is closer but not really.
The issue with Literature and Music there is a beginning, a middle and and a end.
With Software there is a beginning, then the story changes every time the program runs, based on the input at the time. Leading to multiple end points, including a power off.
Music is closer as it had notation that allows for some loops, however this is mostly to keep shorten the notation process and less about workflow.
Also a choose your own adventure book, isn't that good analogy, as there are fixed number of stories possible.
A relatively complex program can have different outcome all the time.
If something is so important that you feel the need to post it on the internet... It probably isn't that important.
I've always been struck by the similarity of code and contracts or laws.
When written well, they define a set of requirements for specific actions to take place, leaving no ambiguity.
When written poorly, you need to know the version of system they are running under, starting circumstances, state of concurrently running processes, etc.
Correct. And just like laws- if regular people can't read what you have written, then likely you are doing it wrong.
Bad law is always overly complex. The more complex it is, the more likely somebody has introduced some ambiguity.
Bad code is also always overly complex. The more complex it is, the more likely it will take a week to do a job that should take an hour when maintaining it.
SJW: a person who perceives an injustice, and while correcting it, commits a greater injustice.
Reading other people's code is a great way to learn better ways of doing things you thought you already knew how to do. ;)
The GOTO statement is reflective of the existential malaise experienced by programmers, and typified in post-modern society.
It shows that the programmer in the code, as in life, feels they have reached a dead-end from which there is no escape, and reflective of a desire to escape the mundane and return to the optimism of youth.
The GOTO becomes a metaphor for man's desire for a quick solution to our problems, and a naive belief we can make the problems go away, and thus becomes symbolic of wish-fulfillment and fantasy to offset the feelings of stagnation and dread so often described in post-modernism.
In stack based languages, the GOTO becomes a surrogate for a strong father figure, and metaphorically kills the mother in frustration. It's also convenient for breaking out of nested logic to an error handler, which gives us feelings of going back to the womb, and indulging in self-infantilism in order to achieve a more expedient resolution of the dichotomy between self and other.
Thematically, the GOTO is both liberation, and the source of our own slavery; it simultaneously demonstrates our desire for freedom, as well as showing the futility of such a quest and how we re-enslave ourselves through our actions.
Because it highlights the existential question of "how do you implement an IF statement without a GOTO in Assembler?", it forces us to acknowledge that, as much as man tries to escape his primitive roots, there persist behavior which is neither rational nor defensible, but which we nonetheless cannot do without from an evolutionary perspective.
The GOTO defines for us the boundary between man as thinking entity, and non-thinking animal. And, as in Conrad's Heart of Darkness, forces us to look within ourselves, and confront the things we see but cannot fully understand or control.
Lost at C:>. Found at C.
Your comment reminds me of this bit about the code for what became Adobe Photoshop. The code is available for download from a link on the page linked to below.
Adobe Photoshop Source Code
Thomas Knoll, a PhD student in computer vision at the University of Michigan, had written a program in 1987 to display and modify digital images. His brother John, working at the movie visual effects company Industrial Light & Magic, found it useful for editing photos, but it wasn’t intended to be a product. Thomas said, “We developed it originally for our own personal useit was a lot a fun to do.” Gradually the program, called “Display”, became more sophisticated. In the summer of 1988 they realized that it indeed could be a credible commercial product. They renamed it “Photoshop” and began to search for a company to distribute it. ... The fate of Photoshop was sealed when Adobe ... decided to buy a license to distribute an enhanced version of Photoshop. ....
Commentary on the source code
Software architect Grady Booch is the Chief Scientist for Software Engineering at IBM Research Almaden and a trustee of the Computer History Museum. He offers the following observations about the Photoshop source code:
“Opening the files that constituted the source code for Photoshop 1.0, I felt a bit like Howard Carter as he first breached the tomb of King Tutankhamen. What wonders awaited me? I was not disappointed by what I found. Indeed, it was a marvelous journey to open up the cunning machinery of an application I’d first used over 20 years ago. Architecturally, this is a very well-structured system. There’s a consistent separation of interface and abstraction, and the design decisions made to componentize those abstractions – with generally one major type for each combination of interface and implementation — were easy to follow. The abstractions are quite mature. The consistent naming, the granularity of methods, the almost breathtaking simplicity of the implementations because each type was so well abstracted, all combine to make it easy to discern the texture of the system. . . .
This is the kind of code I aspire to write.”
Good examples can provide powerful learning experiences. They can crystalize the intangible aspects of description and discussion.
much of left-wing thought is a kind of playing with fire by people who don't even know that fire is hot - George Orwell
Please demonstrate a basic sorting algorithm that a non-programmer can understand that doesn't perform terribly on large lists. You might be able to write a bubble or insertion sort that makes sense to a layman, but for the majority of the population something like mergesort, quicksort, or heapsort is going to seem like voodoo no matter how elegantly it is coded.
A mechanic must know his way around a car to know how to repair it, and I must know my way around the code base if I am to diagnose problems. I can't just focus on the broken parts of it, or changes I make will likely introduce side effects. On most of my projects I didn't even have a requirements document, just a big pile of usually-poorly-written code. Each program is a unique individual machine, as if every single car were built dramatically differently. How much harder would it be for a mechanic if they had to go hunting for the spark plugs before they could even get started?
I'm trying to teach myself to set people on fire with my mind... Is it hot in here?
Knuth disagrees, which is why he created Literate Programming. If you aren't familiar with it, you should make yourself familiar. He suggests eventually someone might win a prize for literature from their code.
If you haven't seen it, you should check it out. His code has a table of contents, and could definitely be considered literature. His Tex code is so well organized, that you can find what you are looking for within 15 minutes, even if you're not really familiar with it. That's how code should be: written so other people can read it.
That's not what the author is talking about, though. He's talking about crappy code that wasn't written in a way that was easy to understand (I read the article; this is my understanding of it). So yeah, crappy code is not literature, or easy to 'decode.' Tautological.
"First they came for the slanderers and i said nothing."
Perl jokes aside, I have some old code written in everything from bash to C to R to Java. The common theme among these absolutely stunning pieces of literature is how incomprehensible some of it can be just a few months later. Sure, good code is self documenting, good code reads like a sentence, a proper module fits on one page of screen (I have a 24" display with better than 1920x1080 resolution, btw) but if my code were indeed prose, it would cause eyes to bleed, to hemorrhage, to explode in a fantastic fountain of blood and aqueous fluid.
Sometimes I wrote bits of code without knowing that there were easier ways. I may do a "for item in $(ls *.csv)" instead of the proper "for item in *.csv" or some furious hackery to manually rotate 20x10 matrix into a 10x20 (single command in several languages), or try to parse an XML file by regex'ing and other madness... Sometimes I was drunk. There was one class where the instructor didn't like "showoffs" so code had to be written using only the commands that were covered in the lecture. The resulting code from that class was horrid. One of my earliest bits of code from the 80s sent escape sequences to a printer and there are several strings with non-ASCII characters. There is no way to understand the code without knowing the printer. I have similar code for an Atari that stored music in a BASIC string. That might be possible to decode only if one understood how the Atari made sound.
but for the majority of the population something like mergesort, quicksort, or heapsort is going to seem like voodoo no matter how elegantly it is coded.
Explaining quicksort to the layman.
Here's a 1000 names on little cards. Pick one at random and look at the name.
Sort the names into three piles - those that come earlier in the list, those that are the same as the name, and those that come later than the randomly selected name name.
Put the "earlier" pile to the left of the "same" pile, and then put the "later" pile to the right of these two.
Great? Done that?
Now repeat on the process on each "earlier" and "later" piles, Do this over and over again, giving you smaller and smaller piles. It doesn't really matter which pile you split first, just as long as you don't mix up the relative left/right ordering.
Eventually you will end up with lots of small piles of cards that contain all the entries of the same name.
And then, as if by Voodoo., all your names are now in order from left to right.
This can be parallelised - if you want, you can out-source some of the work to friends and family, to speed things up.
And yet, once again, I used to teach quicksort to 4th graders- when I was only an 8th grader myself. While it is possible that the general population has gotten significantly less intelligent in the intervening 30 years, it isn't very likely.
If you can't comment in plain english, then your code is not maintainable.
SJW: a person who perceives an injustice, and while correcting it, commits a greater injustice.
BEGIN
:= dream( Christmas [ white ] );
:= firstcard TO lastcard DO BEGIN := dream( Christmas [ white ] );
;
:= firstday TO lastday DO BEGIN := (merry AND bright);
:= firstxmas TO lastxmas DO := white;
(* I'm dreaming of a white Christmas, *)
(* Just like the ones I used to know. *)
IF Christmas [ white ] AND
( Christmas [ white ] = Christmas [ known( me ) ] ) THEN
me
(* I'm dreaming of a white Christmas, *)
(* with every Christmas card I write. *)
FOR index
WITH card [ index ] DO me
END;
(* When the tree-tops glisten, *)
(* And children listen, *)
(* To hear sleighbells in the snow. *)
REPEAT wait UNTIL stateof ( tree.tops ) = glisten AND
stateof( children ) = listen( noiseof1in2( bells.sleigh, snow ) )
(* May your days be merry and bright, *)
FOR index
day.yours[index]
END;
(* and may all your Christmases be white. *)
FOR index
Christmas.yours[index]
END.
When our name is on the back of your car, we're behind you all the way!
I suggest you have a look at an orchestral performer's text sometime. More pencil than ink.
[FUCK BETA]