Readable code

I'vebeen a         memberof  my library sinceIwas
4
years
 old.I guess
   that 'swhy ,I value readabilityveryhighlyand get a    little upset   if.   There are whole sale abuses of agreed typographicnorms.

I'll try that again. I've been a member of my library since I was 4 years old. I guess that's why I value readability very highly and get a little upset if there are wholesale abuses of agreed typographic norms.

La disparition by Georges Perec was a 1969 novel written entirely without the letter 'e'. It was later translated into English with the title 'A Void', and the translation itself was again e-less. That's a pretty incredible feat considering 'e' is the most commonly used letter in the French and English languages. I lasted maybe half an hour before I put the book down, I couldn't go any further. My eyes felt like they were melting. This was simply due to the use of language that was necessary in order to tell the story, but was less than free flowing due to the constraint imposed by the author.

Never mind about constraints, can you imagine of The Lord of the Rings had been written without punctuation? How long would the average reader last before throwing the book away in frustration? Harry Potter without paragraphs? Game of Thrones without space characters between each word? Or even worse, what about a book that occasionally had punctuation, but not always? The odd bit of typesetting, but only when it occurred to the author to use it?

This is exactly the kind of crime against readability software engineers perpetrate regularly, and for no good reason other than laziness and poor habits. The key is a lack of consistency, which leads to ugliness, poor maintenance as people avoid the code and eventually me having a nervous breakdown when I'm asked to look at it.

Ugly code is a particular bugbear of mine. Now, of course, ugliness is in the eye of the beholder every bit as much as beauty, but there are some days when you see some code and you just think 'why?'

Should an opening brace be on a new line or the end of the current one? I don't care.

Should there be a space between 'if' and the parenthesis? I don't care.

Underscores or camel case? I don't care.

Should I use tabs or spaces? I don't care! (well, maybe a little)

Do what you want, just do it consistently, make a coding guideline and stick to it. Your coding guidelines are the typographic standard for your project.

When I read a book I don't want the author to suddenly start using << and >> characters to indicate speech instead of "" half way through. If the author had started with that, fine, no problem, it's the French standard. One isn't inherently better than the other, they're just different. But do not switch!

I have personal preferences, of course I do. Most of my preferences come from my Maths degree. I get upset if I see

    int i=0;

I want to see code breathe. A typical mathematics text book would have spaces, so I much prefer to see

    int i = 0;

And if you really want to face my wrath do this

    for(i=0;i<10;i++)

Or
    someFunction(the_first_argument,a_second_one,and_a_third);

Really? Is there a drought on spaces? You wouldn't read an article that squashed everything up like this and ignored space character conventions, why would you code it this way?

I wouldn't force my preference on anyone, but I know if someone asks me why I code in a certain way I can show that I have reasoned to myself why I want my code the way it is. When I see poor typesetting I know the developer has no such reasoning going on. It makes me wary. If they're lazy about something so basic, what else will they be lazy about?

Code is best if during a review it looks the same as all the other code, the reviewer's eye isn't hitting speed bumps as it fights with new information. The typography is as expected, nothing new has been thrown in. All code in the code base should look like it has been written by a single person, anyone can jump in and start changing it, everyone knows at a glance if thisOldThing is a variable, a function name or something else. Nobody is getting slowed down, production moves at a decent pace.

Your code is telling a story in the same way a book does. Some parts of your code need their own sections, so put them in a function. Other parts are just a small part of a function but are distinct from others, treat them like a paragraph and put some new lines in so they stand out and it's obvious they're related. You won't break anything with whitespace, it's your friend.

I hate seeing functions that look like towering monoliths without a single new line between the first and last lines, it strikes me as insane that someone thinks it's acceptable. And worse, I get upset that someone might be proud of their work. It's cramped, it's dense, it's quite probably hiding a bug that the code reviewer missed because his eyes were glazing over. And as Aldo Cortesi points out in his excellent blog post about code beauty, "Good programmers know that a lack of superficial code quality and consistency is the best indicator of deeper systemic problems in a project." If you learn one thing when it comes to readable code, let it be that.

Number one way to annoy me? It's this:

    if (some_number == some_other_number )
        ...

Can you see it? You might need a magnifying glass but my eye gets drawn to this immediately every time. "(some..." has no space, "..._number )" has one between the variable and the parenthesis.

I know, I'm bordering on psychotic pedantry, but this to me in indicative of something more important. If you are paying so little attention that you can't remember from one end of the line to the next what style you're using I can't trust you with anything more complicated. If you can remember, but don't care, then I won't trust you with anything more important.