Executive Summary: Reasons Why The Code Sucks

inspired by Graph Jam

Lonely Planet for Languages

I've recently noticed a similarity between these 2 phenomena:

• the joy of listing the number of languages which we have worked
• the allure of listing the number of major cities to which we have traveled

Hello, Airport

Most people will qualify their travel list, by saying, "well I've been through London, but just the airport so that doesn't really count". (Indeed, it doesn't.)

I think geeks are less likely to qualify their language list: at least I don't. You won't catch me saying "well I've written Hello, World in Haskell so that doesn't really count".

Now to be honest, I wouldn't even put Haskell on the list, but it is true that a static list of my languages doesn't give anyone a real sense of my experience.

Staying at the Language Resort

A better example, for me, is Python. I have been proselytizing Python for a long time: the spirit of the language appeals to me and I am never happier than when working with the language.

But to be honest, I stay at "Club Python": a sunny resort where the beaches are pristine and the drinks are free. Life is easy.

I've never had to deal with packaging a Python app; I've never had to internationalize one. Or even really debug his/her lousy code in a commercial Python app. I certainly haven't had to deal with scaling issues.

Not to say that this can't be done in Python: I just haven't done it.

Lonely Planet for Languages

To mix metaphors, be sure to evaluate the experience of evangelists. Don't take travel advice from someone who went through the airport. If you are looking for a resort, that's fine, but what we really want is someone who knows where the locals eat and where the food is fresh. A battle-scarred veteran who has suffered an exotic fever and has seen all 4 seasons in the locale. One who has the guts to try speaking the local dialect, and yet the cunning to escape a pub alive when they have inadvertently insulted the national soccer/football team.

For a given language, seek those who could write a Lonely Planet guide for the language.

Executive Summary: charting the act of debugging

A new theme, inspired by the delightful site GraphJam.... Stay tuned for more ahead.

DVD Extras

As part of combating the summer blog doldrums, I am considering a theme of DVD Extras for CodeToJoy.

No, there is no CtJ DVD. Essentially, this is an analogy for outtake photos and other silly posts that were left on the cutting room floor. The tension is that the quality of these posts, by definition, would not measure not up to the usual high standard.

The hope is that the banner of "DVD Extra" would mitigate the "outtake quality" of the posts.

Leave a comment or drop me a line if that sounds interesting...

Code Reviews

Many have noted that it has been quiet here at CtJ HQ. This has been due to vacation, summer activities, and partly the giant vacuum left behind by Twitter (I have resisted the autonomous collective so far). Bloggers tend to play off each other, but the wealth of ideas have been reduced to traikus (an attempt to use the haiku form to communicate, a la "nice try") and other short status updates.

Someone must keep the home fires burning, and so your humble host writes from his quiet perch, while the twittering masses party in the streets below.

This article is a good conversation piece: it lists some elements of code reviews. I could leave a comment, but in the classic tradition, I'll blog mine here.

Prime Directive

I work in open war-room that ranges from 4 to 8 people. The benefits of a war-room are outside the scope of this post, but it may shed light on this element.

The prime directive of an effective code review is to examine the code with an eye to the team philosophy, both from a domain and technical standpoint.

Let's consider technical philosophy first: a team should have a solid, unified view on a variety of issues. Are unit tests required? Do we test getters and setters? How do we handle exceptions? Where do we place inner classes in a file? And so on. (Note that this presumes that the team has read the classics (Effective Java, etc) and that the issues therein are 'settled'.)

The key is to maintain consistency. If there is no consistency or stated philosophy from the tech lead, it should be discussed. But once it has been decided, it should not be debated. All too often, a code review can re-open a debate, but for efficiency, avoid this (unless something isn't working out). IMO, the philosophy should not be written down (the code is the example).

Establishing consistency is a major benefit in a war-room. If a team is still "partying like it's 1999" in cubes, then the stand-up meeting can help here.

The domain philosophy is similar. Questions include: if we upgrade from a previous version, and have 2 Foo objects with the same id, what happens? Should a user be allowed to delete a Foo when it is still linked to a Bar?

Code Coverage

As a reviewer, it is natural to ask if the person wrote unit tests. A good follow-up is to ask them about code coverage. The coverage should meet the level established by the team philosophy. Ditto for code complexity metrics.

Internationalization

Beware of hard-coded strings. Reviewers should always be aware of the context where strings are used, and understand which contexts require locale bundles.

Concurrency

Ask the developer if the code is thread-safe, or if it runs in a multi-threaded section of the code. There is a high probability that s/he will look up at the ceiling involuntarily (that's where all the answers are), and pause for a moment. Hijinx ensues.

Versioning

Universities do not have classes called "Versioning 401" and yet it is one of the biggest challenges we face. With respect to data, the team should be aware of versioning issues. e.g. The lifecycle of data across releases, the migration algorithm, and so on.

This is a giant trap for new persistent objects because often the ramifications are not seen for a long time.

The Upshot

Team philosophy and consistency is important, and there is no better place to see it in action than code reviews. Well, there is one better place: pair-programming. But that's another post.