Code Is Not Literature 240
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.'"
Consider your Audience when writing code (Score:5, Insightful)
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.
Re:What? (Score:5, Insightful)
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.
Re:Similar language, describing different things (Score:5, Insightful)
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.
Re:Similar language, describing different things (Score:5, Insightful)
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.
Re:Consider your Audience when writing code (Score:4, Insightful)
The compiler is not an audience at all. The compiler is the first part of running the code. As far as the compiler is concerned, the code could be obfuscated.
That fact that the code performs it's function is the first economic value of the code. But an equally large, and perhaps greater economic value (or cost) is how well another human can read and comprehend that code later on when managers decide to add pointless features or remove useful features.
Most code is written for economic reasons of some type. Writing code for another human to easily comprehend later increases the economic value of that code -- possibly greatly.
Re:Consider your Audience when writing code (Score:5, Insightful)
Your audience is another human being who will be maintaining that code a few years later.
And he's a violent psychopath who knows where you sleep at night.
Re:What? (Score:5, Insightful)
Reading other people's code is a great way to learn better ways of doing things you thought you already knew how to do. ;)
Re:Consider your Audience when writing code (Score:4, Insightful)
Or yourself a few weeks later, if you're getting old like me and can't remember why you did what you did. This is also why I make an extra effort to ensure the code works the first time, with the fewest possible side effects, so I don't have to maintain it later.
Re:Similar language, describing different things (Score:4, Insightful)
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.
Re:Similar language, describing different things (Score:4, Insightful)
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.
Re:Similar language, describing different things (Score:3, Insightful)
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.
How about Architecture (Score:4, Insightful)
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 [wikipedia.org]. 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.
Re:Music... (Score:4, Insightful)