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.
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.
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. ;)
If you are writing assembler, you _should_ be including a human readable commentary at some level.
If you have put 5000 assembly instructions under a heading titled "object rotation and zoom", with no other commentary, your code _should_ be expelled from the system, regardless of how well it works on the test cases you made up for it.
1. My point is not about how to teach someone how quicksort. It was refuting the commenters assertion that any code not understandble to regular people is bad code. Your quicksort.c file is not going to pick up a deck of cards and demonstrate what it's doing.
2. I'm betting that for 60% of the population out there, they still would not understand how quicksort works after your card demonstration.
Bullshit. Learning about the field of DSP alone takes years of study and books that are 100s of pages long of mathematical background. Code comments are never going to be able to teach someone an entire language and field to someone who doesn't know it. So, again, the fault is not with me or my code if Joe Schmoe doesn't know anything about the language or the problems my code solves.
Probably the best analogy is Architecture. There is a discipline that necessarily has a functional purpose, but still can (and often is) viewed and appreciated as art. A large part of the appreciation of architecture is appreciation of how it went about achieving its functional purpose, and there's a large body of theory build up around this. For example, its is a controversial but generally accepted architectural principle that form should follow function. An implication of this is that unnecessary architectural features are frowned upon. In SW Engineering we call non-functional code "dead code" if it flat out can't be used, and "inelegant" if it is simply more than necessary. Both are generally frowned on.
So if you want to spend time systematically analyzing software as art, perhaps the Right way to go about it would be the way architectural reviewers do, not the way literature or "high art" reviewers do it.
Every time I start to have faith in humanity, I ruin it by driving to work between 7 and 8 am.