styling code

Tue, Jul 22, 2008

With the increased interest in Guanxi, I’ve been forced to take a long look at the coding style I’ve been using, which has meant reading a lot and thinking, do I really want a different style? I’m quite happy with what I’ve been writing over the last 3 years or so but I should at least decide on a style and formalise it, publish Eclipse and IDEA templates and give other developers a chance to format their code to fit in with what’s already there. The problem however is, opinions on how code should be formatted are as personal as how you wash yourself in the morning, or not, depending what language you use. I believe Perl programmers are devoid of soap. Untidy desk, untidy mind, as they say. What about untidy code? Perl is like an explosion in a character factory. Even more so when it’s been written by an academic with a Perl for Dummies book. It takes someone who really loves to code to write readable Perl code. Given that most academics code as a knee jerk reaction to some crisis or to intellectually spar with colleagues.

Luckily I don’t use Perl much now. I ported a lot of what I wrote to PHP and started looking at Ruby, although I much prefer Python these days and I have very strong opinions on how code should be formatted, as befits my years in the business of coding. So what are my pet hates?

I can’t stand formatting like that. I prefer contextual blocks of code. Everything inside a try block is aiming to do something. Everyting in the catch block is aiming to do something completely different. They have nothing in common. One is triggered by events in the other but other than that, they are distinct and unrelated. Think about it. You’re sitting at your desk, muching on a cake and the fire alarm goes off.

One minute you’re eating cakes and the next you’re running for the stairs. There is no relation between the two states other than the latter was triggered by an event that the former was interested in. But the way the code is formatted, the latter intrudes on the former’s territory. I can’t eyeball that and identify blocks of functionality. I need to see the blocks as separate entities:

now I can see exactly what’s going on.

So what’s next? Parenthesis!

this is just so, I don’t know, comp-sci! This code has the stutters. You couldn’t listen to someone who spoke the way this code was formatted. It’d be all “umm” and “err” and “mmm” and crap like that. It’s whitespace bloated and difficult to read. It’s the equivalent of those dusty lecturers who use overhead projectors and reveal the content line by line using a sheet of paper. It’s code roadkill. It’s been flattened by a steamroller.

now, that’s much better! It’s syntactically tight. There’s no waffle and bull. It gets straight to the point.

Now what about temporary variables? Use them when you need to, otherwise, let the context of the code speak volumes:

do this instead:

if you can’t work out what config means, not to mention getLogger() and then .info on that class, then perhaps you should consider a career change. Baking perhaps?

And that leads me on to one of the worst crimes in coding that can be perpetrated. Short and meangingless variable names:

what the *** is c? I’ve seen this a lot over the years. It’s slovenly and lazy coding. At a cursory glance the code is impossible to read. You can’t work out what’s going on. You need a big and beefy IDE to do the legwork for you, following declarations and definitions and usages. It’s like you’re walking down the street and you need an interpreter to speak to people you meet, even though they speak the same language as you. “i o ff er uf io”, “err, What did he say?” Following the IDE back through reams of bad code might get you here:

so you should do this instead:

let the code carry the context, for without context and meaning, the code is useless and unmaintainable.

I’ve only scratched the surface on code formatting but my other opinions are too expletive-ridden to print! but I’ll leave you, dear reader, with an exception to the ranting. Professional obfuscation. njoy ;)

comments powered by Disqus