Forgot your password?
typodupeerror
Programming Education

Code Is Not Literature 240

Posted by Soulskill
from the neither-are-tea-leaves dept.
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:
  • Music... (Score:2, Interesting)

    by Anonymous Coward
    ...works much better as a model. Performing music is analogous to executing code.
    • Re:Music... (Score:5, Funny)

      by jellomizer (103300) on Tuesday January 21, 2014 @03:42PM (#46028497)

      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.

      • Never read a "choose your own adventure" did you?
        • Never read a "choose your own adventure" did you?

          "Choose your own plot" books have a very limited number of choices. The number of possible paths through code increases exponentially with the size of the program. Literature usually has the meaning the author intended. If you are reading code, it is usually because it does NOT do what the author intended.

          • Re:Music... (Score:5, Funny)

            by camperdave (969942) on Tuesday January 21, 2014 @07:38PM (#46030703) Journal
            BEGIN
            (* 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 := dream( Christmas [ white ] );

            (* I'm dreaming of a white Christmas, *)
            (* with every Christmas card I write. *)

            FOR index := firstcard TO lastcard DO BEGIN
            WITH card [ index ] DO me := dream( Christmas [ white ] );
            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 := firstday TO lastday DO BEGIN
            day.yours[index] := (merry AND bright);
            END;

            (* and may all your Christmases be white. *)

            FOR index := firstxmas TO lastxmas DO
            Christmas.yours[index] := white;

            END.

      • by mcgrew (92797) *

        What you guys are missing is that you're decoding the words on the screen right now. Reading just doesn't feel like decoding, especially if you're any good at it at all.

        My daughter is like that with sheet music. Give her a clarinet and sheet music for a song she never heard and she'll just play it. I decode musical notation like a five year old decodes Dr. Suess, she reads music like I read books.

        I use to write software, first as a hobby and later compiled PC databases and NOMAD mainframe coding at work (ac

        • by iluvcapra (782887)

          What you guys are missing is that you're decoding the words on the screen right now. Reading just doesn't feel like decoding, especially if you're any good at it at all.

          Right, but decoding is just the translation from one symbology into another, it doesn't create a semantic relationship, decoding can't create meaning, not in the sense we mean here. I can read your for loop, I can tell you it'll run node->count times, but you are the only one that actually can relate node->count to something in the re

        • 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.

      • by turp182 (1020263)

        So code is jazz?

  • Code is very similar to language. How would it not be?

    However, what's being described is entirely different. A narrative relies on both clear expression of the action and a broad context of details to give it resonance.

    Code, on the other hand, operates through loops and definitions independent of timeline, so is a better match for architecture and math than the science of communications.

    • 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.

        • Re: (Score:2, Interesting)

          by Anonymous Coward

          if regular people can't read what you have written, then likely you are doing it wrong.

          That seems like a stupid standard. What if that "regular" person simply has no experience in what you wrote? If I write perfectly good SIMD assembly and this mythical "regular" person can't read and follow it because they are unfamiliar with x86 MMX/SSE/AVX how is that my fault and why would that me my code bad?

          • 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:06PM (#46028775) Homepage

          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.

          • When I use voodoo, I usually include hyperlinks to Wikipedia or similar sources explaining what's going on. Even when the links die, you can usually search on the algorithm names to come up with an explanation.

            More often, I let the library deal in the voodoo and my code reads like: while ( input ) { insert } sort.

            • by Splab (574204)

              I usually leave links to youtube like this one:
              http://www.youtube.com/watch?v... [youtube.com]

              (Not rick roll)

              Might not help, but at least the programmer knows that the guy who wrote this is sorry (and that he is aware of how bad that piece of code is).

          • Re: (Score:2, Informative)

            by Anonymous Coward

            How about sorting a deck of cards using two of the algorithms you mentioned, quicksort and mergesort.

            Quicksort: Take a deck of cards, and pick a random card. Form two new decks by placing all cards smaller than it to the left deck and the larger or equal ones to the right deck. Repeat this for both decks, so you get more decks. Never move a deck over another. At the end just combine the decks from left to right in increasing order.

            Mergesort: 1. Place all cards on the table, each on its own slot. If there's

          • by hamster_nz (656572) on Tuesday January 21, 2014 @04:47PM (#46029223)

            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.

          • Quicksort is just a double direction bubble sort. Mergesort, I'd agree, might seem like voodoo. Heapsort? That's just a filing cabinet.

            • Mergesort isn't all that difficult to explain either. Take your unsorted list and divide it into a bunch of single-element (trivially sorted) sublists. Divide the sublists into pairs, and merge each pair of sorted sublists into a new sorted sublist; to merge two sorted lists, repeatedly take one element from whichever list starts with the lowest value until both lists are empty. If you happen to end up with an odd number of sublists, hold the extra one for the next round. Repeat the pairing and merging unti

          • > is going to seem like voodoo no matter how elegantly it is coded.

            Mostly true, however, beautiful and simple code makes it a helluva lot easier to understand ! Quicksort isn't _that_ difficult to write from the ground up if you understand the i) the theory, and ii) can apply it.

            * Three Beautiful Quicksorts -- The most beautiful code I never wrote.
            http://www.youtube.com/watch?v... [youtube.com]

            From

            * Beautiful Code: Leading Programmers Explain How They Think (Theory in Practice (O'Reilly)) [Kindle Edition]
            http://www. [amazon.com]

          • 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.

            I did one once. It was a Shell-Metzner sort.

            The list was large, but almost completely ordered. In other words, a pathological worst case for the heaping sorts. Also a bad choice for basic bubble, but a Shell sort does a binary bubbling that was optimal for the data in question. And very welcome, since one of the main systems in our shop had to do this about 150 times a day.

            "Efficient" means different things, depending on context.

          • by ndykman (659315)

            Take a stack of cards with a word on them. Split them in half. Continue to do so until you have a lot of piles with two cards.

            Starting at the first two piles, make sure both the piles are in order, by switching the cards if needed.

            Now, merge the first two piles. To do this, look at each card in the second piles. Insert the card into the first pile so the pile is still ordered. This will give a new pile of three or four cards.

            Do this for the next two piles of two cards. When you reach the end of the two card

        • by Sique (173459)
          Bad laws don't need to be overly complex. Bad laws are just that: bad. You can have very simple laws which in general create a bad outcome.
        • by Nemyst (1383049)
          The problem with that criterion is when your code depends on an API which would never ever be understood by a regular human being. Sometimes you just can't avoid it.
      • "Well written" and "law" is a contradiction in terms.

      • by turp182 (1020263)

        Great analogy, it could be extended such that code faults leading to things like buffer overflows or SQL injection are "loopholes", basically unexpected consequences.

        And patching the law is far more difficult than patching software.

      • by ATMAvatar (648864)
        Also: there's a large group of people constantly looking for and exploiting holes, and sometimes holes are intentionally added.
    • So Gamebooks [wikipedia.org] are not literature then?

  • Since when was I required to do code reading as an exercise? I've never heard of such a thing.

    Can people stop inventing stupid new things I must do to be the perfect programmer?

    Do not invite me to your code reading club. I'll decline the invitation.

    • Re:What? (Score:5, Insightful)

      by Dan East (318230) on Tuesday January 21, 2014 @03:40PM (#46028471) Homepage 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.

      • 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. ;)

        • Re:What? (Score:4, Funny)

          by RabidReindeer (2625839) on Tuesday January 21, 2014 @05:25PM (#46029543)

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

          Reading the source code to the OS and compilers used at my school probably taught me more than the classes themselves.

          It was good code. Most of the business code I've seen is more like pornography than great literature, though.

      • Re:What? (Score:5, Interesting)

        by cold fjord (826450) on Tuesday January 21, 2014 @04:02PM (#46028713)

        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 [computerhistory.org]

        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.

    • Since you ever found employment at a firm which has existing code that they want to continue to use and evolve?

  • Discussing the meta-narrative implied by errant GOTO statements? Considering the motivations of while loops? Debating the thematic development in variable naming schemes?

    Learning from anything means analyzing it, knowing what goes where for what reason, and then thinking about if there are other ways to do it, better ways to do it, if it needs to be done at all, etc. When you're reading with the intent to understand and you're doing something that's not appreciably different from simply 'viewing words' you'

    • by bob_super (3391281) on Tuesday January 21, 2014 @03:40PM (#46028465)

      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.

    • by Anonymous Coward on Tuesday January 21, 2014 @03:41PM (#46028477)

      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.

      • If I hadn't already taken part in this discussion I would upvote you. ""GOTO!" he cries out," is a brilliant line and should really be the opening of 'Waiting for GOTO'

    • by gstoddart (321705) on Tuesday January 21, 2014 @03:56PM (#46028639) Homepage

      Discussing the meta-narrative implied by errant GOTO statements?

      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.

  • by DavidHumus (725117) on Tuesday January 21, 2014 @03:29PM (#46028361)

    There is a (rather small) minority view that code can actually improve our ability to think - http://www.jsoftware.com/jwiki... [jsoftware.com] . However, the bulk of opinion sees code as an obstacle to be overcome - rightly so, given the sloppy, ad-hoc construction of most programming languages.

    • Code itself is simply a set of rules tying words and symbols to operations on a system. Learning those rules won't make you better at anything but learning rules. What will help you develop as a thinker is learning the underlying theory and ideas of a closely related field -- computer science. Thinking up your own solution to the dining philosophers problem, the knapsack problem or even understanding how you can describe the solution to the towers of Hanoi as an iterative process all help you develop proble

      • Hogwash. One of the fundamentals of programming is understanding the machine or system and the "rules" for controlling it. How are you to develop an algorithm for solving the towers of Hanoi on a specific system if you don't know whether or not that system is capable of recursion (or perhaps even requires it)? How are you going to handle input and output without knowing the "rules" for the interfaces? High level algorithms can be solved by mathematicians but computer scientists use "rules" to make the machi

      • This is an extremely blinkered view of code that probably well-represents the majority opinion, given that that's the genesis of most programming languages.

        However, there is a small group of languages that aspires to represent computational concepts at an abstract level in a clear, consistent, and logical manner. These languages, like APL and J, are based on a regularization of mathematical notation.

  • 80% of the code of a program is uninteresting and mundane. As a programmer, you want to get to the core nugget of a problem, suss it out and solve it. "Reading" code is the same thing. You want to decode the structure, find the interesting 20% and move on to gleaning whatever you can from it. It's in our nature.

  • 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.
    • by Alomex (148003)

      When writing code, your audience is not the compiler. When writing code, your audience is not the compiler.

      Sir, I'm a member of the language police and I just pulled you over for a stupid over generalization for effect infraction.

      Your audience is of course both the compiler and the other human being maintaining the code after you. A good programming language walks this fine line. Prolog was too much on the human side, Perl is too much on the interpreter side.

      • 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 Alomex (148003)

          Bad code can be written in any language.

          And this in no way contradicts that some languages are better than others for that purpose. For a simple example consider the original COBOL syntax of

          ADD 1, N GIVING N

          This is sucky, harder to read code than n := n+1 or n++

          As far as the compiler is concerned, the code could be obfuscated.

          You have no idea how compilers operate if you believe this. The compiler is interested for example, in teasing apart dependencies so it can apply optimizations. Here's an example of badly written code in terms of the compiler:

          If Test(Water, Wet) then
          blah

          the compiler will be u

          • by Obfuscant (592200)

            And this in no way contradicts that some languages are better than others for that purpose. For a simple example consider the original COBOL syntax of ADD 1, N GIVING N This is sucky, harder to read code than n := n+1 or n++

            Algebraic notation is easier if you know algebra and that it really isn't algebra despite the similar appearance. "n++" in particular requires knowledge of pre and post increment ops. The COBOL, on the other hand, is almost English. If English isn't your language COBOL is hard.

            And I still remember the elegance of the:

            MOVE CORRESPONDING A TO B.

            COBOL syntax. It was a very fresh alternative to other early languages where you had to do this operation one field at a time. And if you modified the struct but

            • by Alomex (148003)

              Not sure what to make of your post. It is universally agreed that ADD 1, N GIVING N was a mistake.

              The fact that COBOL has some other constructs that are nice (and indeed it does) in no way disprove my statement that a language can make a statement inherently easier to understand.

              Another simple example Algol/Pascal's n := n+1 is preferable to C/C++/Java's n=n+1 because this last can be confused with an equality test.

              If you have made z a global so that it is in scope for function f as well as the main code the compiler will know this, as will the programmer.

              I don't see what your comment has to do with my statement that the compiler cares about c

            • by Rockoon (1252108)

              "n++" in particular requires knowledge of pre and post increment ops.

              No it doesn't. Nothing about it requires knowledge of pre-increment or post-increment since their is no dependency on either. All you need to know is that it increments, and thats all the compiler needs to know too.

      • by gstoddart (321705)

        When writing code, your audience is not the compiler. When writing code, your audience is not the compiler.

        Sir, I'm a member of the language police and I just pulled you over for a stupid over generalization for effect infraction.

        Well, as another member of the language police I'm required to remind you that including the quote twice for effect is a breach of hyperbole rule #17-c, and is, in effect, an equivalent infraction.

        Your section chief has been notified, and you will be required to take language reme

    • 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.

      That's one of my peeves. When I see a comment like that, I scream (usually silently) that I know you're assigning foo to x. I want to know WHY you're assigning foo to x!

      • by DickBreath (207180) on Tuesday January 21, 2014 @03:57PM (#46028649) Homepage
        > That's one of my peeves. When I see a comment like that, I scream . . .

        When someone does it, then put the following optimizations into their header files somewhere. Be sure to include the useful comments that explain their purpose.

        #define struct union // optimization to use less memory
        #define while if // optimization to make code run faster

        It's the thought that counts.
      • . When I see a comment like that, I scream (usually silently) that I know you're assigning foo to x. I want to know WHY you're assigning foo to x!

        Sometimes I mischievously add comments like that to the code, just because I know how happy it will make some people. //explain why I add comments like that to code

    • 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.

      • 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

        This quote is currently on our whiteboard at work right now.

    • by Ichijo (607641) on Tuesday January 21, 2014 @03:57PM (#46028659) Homepage 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 khr (708262)

      When writing code, your audience is not the compiler.

      If you're primary audience is not the compiler why are you writing code at all? If the compiler isn't your primary audience, just tell another person what you want done...

  • by Greyfox (87712) on Tuesday January 21, 2014 @03:41PM (#46028485) Homepage Journal
    I've read a lot of code over the years and thinking back on it, I do kind of approach it that way. What I'm doing feels more akin to taking a machine apart to see how it works rather than reading it as I would a book. I often feel, when I'm interrupted, like I'm ass-deep in wires that are going every-which-way.

    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.

    • Most code is not in a style we recognize, so it requires decoding. Some code is recognizable, and it is read like literature, no decoding.
      Java or .net where most of the code is calling the framework, can be read if it is not overly clever. STL or rigorous C++ can be read.
      Any major shift from the expected paradigm requires parsing, of course.
      Being familiar with design patterns and best practice means you can read more and decode less, and have more to draw on.
      So yeah, it is both reading or decoding, dependin

  • I disagree completely. A program resembles literature on two levels.

    First, the code itself uses an extremely rigid grammar to express the requirements of the program. This expression can be simple or complex; clear or muddled. The extent to which the author (in every sense of the term) expresses these clearly and elegantly determines how likely the code is to succeed at its original purpose as well as how easy it will be to maintain.

    Secondly, the UI (if present) is also a realization of the ideas behind the

  • Complex code is not just a specimen. It is an ecosystem, where your crazy beetle consumes crazy aphids and evades crazy ants, while simultaneously trying to reproduce itself and the entire ecosystem to the best of its ability. A crazy beetle would not eat anything standard, like say make or autoconf. No, his refined palate requires a more sofisticated tool like imake, cmake, or even an internally grown food made of ground up pythons. Eating and reproduction habits may also be equally crazy all on their own.

  • by HeckRuler (1369601) on Tuesday January 21, 2014 @03:51PM (#46028571)

    No no, certain parts of coding is very much like literature. The style of how you... branch based on a string, or how you implement event-driven coding, or how you distribute computing power.
    There are a TON of ways to skin those cats and which way you do it is a matter of stylistic preference. It's fashion. The exact sort of subjective shindig that lit major whittle away their time with. It's like the difference between writing in first person or third person. And in certain places one way is very much better than the other.

    But who the hell reads code for the stylistic appreciation? We read code because it's broken, we want to steal part of it, or we need it to do something else. That's not a stylistic issue, that's a mechanic wrenching on a car. Figuring out just what the hell it's doing is a different act than bickering how it could have been done better. Doing the first part pays a lot better than the second.

    This guy has noticed that most people that read things are reading restaurant menus, technical documents, text books, grocery lists, and not novels. The writers of said material are doing it to get shit done rather than fretting about how they do it.

    • by Greyfox (87712) on Tuesday January 21, 2014 @04:08PM (#46028799) Homepage Journal
      But but but! A mechanical object can be beautiful, and so can code! Often I've seen brilliant and occasionally sadistic approaches to the problem that I can definitely appreciate at an artistic level. Something like Duff's Device [wikipedia.org] requires both technical brilliance and a good amount of creativity. I have to read and analyze code for my job on a regular basis.

      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?

      • by iluvcapra (782887)

        Duff's device always struck me as sort of a crank idea, it's more of a trick than a clever algorithm. The fact that you can stick some case labels inside a do/while and some outside would be considered totally breaking if you were to do it under any other circumstance, you're effectively using a label to jump into a scope (even though in this case it's harmless). Also, this is the 21st century: if you find yourself actually pasting Duff's device into your project, you're probably haven't read about all of t

  • Unlike literature, Art, music, etc., code has very little redundancy. In fact, low redundancy is a quality measure for code. Hence "reading" is an entirely unsuitable approach, as "reading" relies on relatively high redundancy on all layers.

    IMO somebody that does not understand this beforehand does not have any real understanding of what code is.

  • by istartedi (132515) on Tuesday January 21, 2014 @04:13PM (#46028863) Journal

    I don't see how any programmer would think code was literature, except perhaps highly technical literature. You read novels from beginning to end. You read code on an as-needed basis. You might only read the header of a library. In fact I've seen good libraries where the only docs I read were long comments in the header file. If you want to understand a system you might start with main() or your language's equivalent and find some kind of dispatch function with calls to things like ResizeWindow which is *boring* and calls to things like DetectThief which is *interesting* so you drill down into the DetectThief function and find out where it gets the data and how it decides the user might be a thief. That might only be a few thousands lines that you've looked at. The other 30k lines of GUI or sorting, or options of writing PDF reports... blah, it might not be interesting to you... unless you're a font and layout geek and the reports did something interesting with fonts and/or layouts. Then you might only read that part.

    Likewise, if it crashes you'll pull it up in the debugger and read parts of the functions on the stack that lead to the crash. Aha! The contract called for the caller to not pass any NULL pointers, and they passed one. Fix. Commit. You had a *reason* for reading that code.

  • Knuth disagrees (Score:5, Interesting)

    by phantomfive (622387) on Tuesday January 21, 2014 @04:14PM (#46028873) Journal
    Knuth disagrees, which is why he created Literate Programming [wikipedia.org]. 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.
    • When he said " A piece of code is not literature; it is a specimen.'" I was thinking that might apply to HIS code but that does not describe the code that good coders are trying to produce.

      Also "specimen" implies the code is dead, when most code is very much alive and in flux...

    • Knuth disagrees...

      Knuth (and many others) think code should be more like literature, but to successfully create a code reading culture you must acknowledge that in practice examining most code is not at all like reading literature and instead needs to be approached more like a scientific investigation. Knuth actually provided an anecdote that reinforces this point so I very much doubt he disagrees with it.

      • by phantomfive (622387) on Tuesday January 21, 2014 @09:13PM (#46031605) Journal

        to successfully create a code reading culture you must acknowledge that in practice examining most code is not at all like reading literature and instead needs to be approached more like a scientific investigation

        OK, so that's an interesting hypothesis, what evidence do you have to support your hypothesis? Doesn't it make more sense that if you want people to read your code, you should make it easy to read (that is, make it literate)?

        Knuth actually provided an anecdote that reinforces this point so I very much doubt he disagrees with it.

        I read Knuth's Literate Programming, and I would say I accurately portrayed his viewpoint. Would you like to read the book and tell me how you think I misunderstood it? To restate, Knuth doesn't think all code is literature, he thinks code can be literature, and he taught how to get there.

  • Sounds like he needs to read "The Chosen" by Chaim Potok, where he'd find another analogy. Then he could try the chevruta model.

  • The only surprising thing is that it's taken this long for him to figure this out.

  • by digitalhermit (113459) on Tuesday January 21, 2014 @04:25PM (#46028993) Homepage

    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.

    • Oops, hit submit instead of preview, and forgot to log in... Take 2:

      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.

      Heh. My favorite bit of code written for 1st-year C class was a simple function to convert grades from a numeric percentage to a character representing the letter grade. (Breaks were inclusive and at 10% increments, so 90-100%=A,80-89%=B, etc.) This problem was of course assigned at the end of the lecture introducing switch/case.

      My code was something like:

      char grade(int percent) {
      if(percent < 50) percent=50;
      return 'A' +

    • by mdielmann (514750)

      Translation:

      1: Don't code drunk.
      2: Self documenting code isn't actually self documenting.
      3: Non-self documenting code (hardware-specific strings/code) is also not self documenting.

      Therefore, don't code while drunk, and comment your code. Even if it seems obvious, summarize any block of code, so when you come back to it months (or years!) later you'll have a clue of what it was supposed to do, and then maybe you'll be able to figure out what you were trying to do in the first place.

      This is based on my

  • This may explain why the incredibly ancient feature request for an "Outline View" in OpenOffice has gone over a decade (Reported: 2002-04-10) with no resolution.

    https://issues.apache.org/ooo/... [apache.org]

    The mental mapping of code for programmers and the mental mapping of text to those of us who write literature and non-fiction is totally different. They can't visualize how an outline and headings and the cues fonts give readers differs from all the "mind maps", "document navigators", and other inadequate replace

  • by j33px0r (722130) on Tuesday January 21, 2014 @04:46PM (#46029211)

    We don't read poetry, we decode it. Or maybe you would say that we interpret it? Depends upon your point of view. We don't read the original article, we skim it.

    The original author is romanticizing the term literature, not that there is anything wrong with that of course, but literature is a term applied to everything from Dostoevsky to instructions for assembling a toy. Beautifully/Dreadfully written code could be labeled as art, poetry, literature, garbage, puzzling, cryptography, and a whole variety of other terms.

    With all that being said and putting aside that I do not agree with the original author's definition of literature, I do appreciate their perspective.

  • Just reading the summary, but this guy sounds off-base. There are different "densities" of writing, ranging from children's books and newspapers on one end, to stuff like academic journals, math, and poetry on the other end. Those latter types expect a much slower rate of progress, and more questioning-probing-ruminating on the text as you go. As usual, computer code is a lot like math. The author need not go so far afield for a good analogy.

  • we could just treat code as though it were code.
  • In other news ...

    Oil is not Tea.

    No more to ad.

  • 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 [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.

    • 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.

      The problem is... so long as the building doesn't fall down, architectural reviewers review architecture in exactly the same way that literature and "high art" reviewers review their field. It's all about buzzwords and status and soft theory. The engineering is left "as an exercise for the student" and

...when fits of creativity run strong, more than one programmer or writer has been known to abandon the desktop for the more spacious floor. - Fred Brooks, Jr.

Working...