Become a fan of Slashdot on Facebook


Forgot your password?
Programming Education

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.'"
This discussion has been archived. No new comments can be posted.

Code Is Not Literature

Comments Filter:
  • by DickBreath ( 207180 ) on Tuesday January 21, 2014 @03:35PM (#46028441) Homepage
    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.
  • Re:What? (Score:5, Insightful)

    by Dan East ( 318230 ) on Tuesday January 21, 2014 @03:40PM (#46028471) Journal

    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.

  • by JoeMerchant ( 803320 ) on Tuesday January 21, 2014 @03:48PM (#46028547)

    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.

  • by DickBreath ( 207180 ) on Tuesday January 21, 2014 @03:52PM (#46028585) Homepage
    The programming language is irrelevant. Bad code can be written in any language. Really good code is an art in any language.

    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.
  • by HeckRuler ( 1369601 ) on Tuesday January 21, 2014 @03:53PM (#46028609)

    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)

    by Anonymous Coward on Tuesday January 21, 2014 @03:54PM (#46028619)

    Reading other people's code is a great way to learn better ways of doing things you thought you already knew how to do. ;)

  • by Ichijo ( 607641 ) on Tuesday January 21, 2014 @03:57PM (#46028659) Journal

    Your audience is another human being who will be maintaining that code a few years later.

    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.

  • by JoeMerchant ( 803320 ) on Tuesday January 21, 2014 @04:17PM (#46028897)

    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.

  • by Stormy Dragon ( 800799 ) on Tuesday January 21, 2014 @04:32PM (#46029059) Homepage

    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.

  • by Anonymous Coward on Tuesday January 21, 2014 @05:17PM (#46029483)

    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.

  • by T.E.D. ( 34228 ) on Tuesday January 21, 2014 @06:00PM (#46029881)

    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.

  • Re:Music... (Score:4, Insightful)

    by nschubach ( 922175 ) on Wednesday January 22, 2014 @12:07AM (#46032617) Journal
    If musicians read sheet music like programmers read code, then why do a lot of programmers insist that everyone else comments their code? Do musicians insist that every other musician make comments on why they chose to raise the octave or what they were thinking when they chose that chord?

    // WTF was Beethoven thinking here...

    // This note wasn't right, I dropped it twice.

    // This part is the chorus, it will be played several times.

Syntactic sugar causes cancer of the semicolon. -- Epigrams in Programming, ACM SIGPLAN Sept. 1982