I'm James Hague, a recovering programmer who has been designing video games since the 1980s. This is Why You Spent All that Time Learning to Program and The Pure Tech Side is the Dark Side are good places to start.
Where are the comments?
Learning to Ignore Superficially Ugly Code
Back when I was in school and Pascal was the required language for programming assignments, I ran across a book by Henry Ledgard: Professional Pascal. Think of it as the 1980s version of Code Complete. This was my first exposure to concerns of code layout, commenting style, and making programs look pretty. At the time the advice and examples resonated with me, and for a long time afterward I spent time adjusting and aligning my code so it was aesthetically pleasing, so the formatting accentuated structural details.
To give a concrete example, I'd take this:
and align it like this:
The theory was that this made the repeated elements obvious, that at a quick glance it was easy to see that three music files were being loaded. Five or six years ago I wrote a filter that takes a snippet of Erlang code and vertically aligns the "->" arrows. I still have it mapped to ",a" in vim.
More and more, though, I'm beginning to see code aesthetics as irrelevant, as a distraction. After all, no one cares what language an application was written in, and certainly no one cares about the way a program was architected. How the program actually looks is far below either of those. Is there a significant development-side win to having pleasingly formatted code? Does it make any difference at all?
In the manual for Eric Isaacson's A86 assembler (which I used in the early 1990s), he advises against the age-old practice of aligning assembly code into columns, like this:
His view is that that the purpose of a column is so you can scan down it quickly, and there's no reason you'd ever want to scan down a list of unrelated operands. The practice of writing columnar code comes from ancient tools that required textual elements to begin in specific column numbers. There's a serious downside to this layout methodology, too: you have to take the time to make sure your code is vertically aligned.
How far to take a lack of concern with layout aesthetics? Here's a quick test. Imagine you're looking for an error in some code, and narrowed it down to a single character in this function:
The fix is to change the first index from 1 to 0. Now when you were in there, would you take the time to "correct" the formatting? To adjust the indentation? To remove the inconsistencies? To make the variable names more meaningful? Or would you just let it slide, change the one character, and be done with it? If you do decide to make those additional fixes, who is actually benefiting from them?
(If you liked this, you might like Macho Programming.)