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:

win_music_handle = load_music("win.aiff");
bonus_music_handle = load_music("bonus.aiff");
high_score_music_handle = load_music("highscore.aiff");

and align it like this:

win_music_handle        = load_music("win.aiff");
bonus_music_handle      = load_music("bonus.aiff");
high_score_music_handle = load_music("highscore.aiff");

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:

add     eax, 1
sub     eax, ebx
call    squish
jc      error

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:

void amazing_adjustment(int amount)
    {
      int temp1 = Compartment[1].range.low;

      int temp_2 = Compartment[ 2 ].range.low;
   int average = (temp1 + temp_2)/2;
   Global_Adjustment =
      average;
}

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

Comments

(hilariously, in the RSS feed and/or google reader, the example function ends up as a single line).

I would personally fix the indentation because I have a tool (git log/blame -w) that lets me ignore the whitespace differences in a commit and focus just on the textual changes.  But that’s because my anger at ever seeing those lines again would be a hit to productivity.

Posted by dbt on 13 Dec 2010 at 04:29

I would personally fix the bug and then fix the layout in a separate commit.

I think your other examples kind of contradict each other. Eric Isaacson is right that there isn’t much use in scanning a column of operands in assembly code. But in your first example, being able to scan that right hand column and see that they are all load_music() calls *is* useful and contributes to making the code faster to understand and easier to maintain.

Posted by Anders on 13 Dec 2010 at 17:27

Great common sense here. Wish I’d thuohgt of that.

Posted by Kindsey on 05 May 2011 at 17:35

Add comment