Tuesday, 24 February 2009

James Joyce .NET

Last week, after doing a code review, I coined the term "James Joyce .NET". Though the James Joyce factor isn't particularly .NET specific (I'm sure there are Ruby, C++, Java, and most certainly C developers out there who do things in similarly cryptic manners), I think the term has a nice ring to it. And in fairness to Joyce, I think the code I reviewed was far less readable than Ulysses.

Aside from software that works and "does its thing" in a reliable manner, clients care a lot about code that's maintainable. The client may not know that they care about this, at least not at first - but once you tell them that a change is going to take three weeks to complete "because of this, that, and the other" (because the code you've written isn't maintainable) you bet your sweet ass they start caring. They care not because of the state of your code; they care because of the cost. And rightly so.

There are many key things to consider when writing maintainable code but the subject of my current rant will be readability. Does your code read like a book? Probably not (hey, it's not fiction) - and that's OK. But do your method names and signatures read like sentences? Could you translate the body of your methods into short little textual paragraphs that clearly illustrate what they do? If you answered "no" to both of these questions it's probably time to stop and think a little.

Disclaimer: I'm renowned for harping on about ideals and I've been caught out many a time falling short of my own mark. That said, I stick to my ideals because without them we've got nowhere to go.

To start with, code must be legible. That means you have to choose names (for your classes, methods, parameters, variables) that clearly indicate purpose. Favour readability over brevity when creating names. Second, your names must make semantic sense. A class-method name combination should be completely unambiguous, easy to read, and clearly convey "what you get". Classes and methods should do what it says on the tin. Don't be obscure, don't be ambiguous.

Third: Use the appropriate constructs for the job. Don't embed an algorithm in a property. Don't use private properties. Properties are there to expose aspects of a class, so if you're not going to expose it, use a private member variable instead. Don't use indexers for anything but accessing collection data. Don't use generics unless you need generic code, and then only if generics give you something that a typed parameter list doesn't (using interface/abstract classes instead of concrete types).

Seriously, think long and hard about any code you write. Just because something works doesn't make it good. And give some thought to those people that come after you. Will they be able to understand what you've done? You might very well be a genius and the best thing since sliced bread but really, what good is that if nobody understands what you've done? Don't obfuscate your code by being lazy, too clever, or by using constructs in a way that they were not intended.

</ rant>

No comments: