implements Elegance {

From There Are No Famous Programmers.

[T]oday I was offered a system administrator job, again. It was very humbling to say the least. It kind of knocked me out to have someone think through all the things their company needs and the only thing they could think I'd be good at was system administration.

Yep, just a system administrator. Still.

I still have to do programmer interviews like everyone else. No matter how much code I put out, I still have to solve stupid puzzles about coconuts and manholes. No matter how many web servers or email frameworks or database servers or chat servers or assemblers I write I still have to prove I can code. No matter how many copies of my software get deployed I still have to prove I can make reliable software..

If, with his obvious achievements. Zed Shaw gets mistaken for someone to do sysadmin work, maybe much less accomplished guys like me should just give up.

Having said that, what‘s the alternative?

The view I have developed about code comments is informed by years at the coal face of software development and re-enforced by what @unclebobmartin has to say about them in Clean Code, which I read last year and continue to refer back to.

Stale comments lie.

In my opinion, commenting code is the laziest way of expressing intention or semantics in code. Why? Because comments are not code. They are not an integral part of the running program. They are not bound by syntax or verified by unit testing.

This wouldn‘t be so bad if that code were never subsequently to be changed. Code is always changing. As agilists we‘re always tweaking and refactoring our code to reflect new or changing requirements. It‘s all part of embracing change. There is therefore nothing (beyond attentive human inspection) to prevent comments from becoming stale, detached or irrelevant. Stale, detached or irrelevant comments are worse than no comments. Opaque code with no comments merely obfuscates, opaque code with stale comments lies.

So what‘s the alternative? It is is more–or–less accepted wisdom now that if it is unclear what some code does (or at least what is intended) by reading it then it should be refactored so that it is clear, elegant and expressive. Rename methods, extract unclear code into new methods and classes, reduce responsibilities.

This is all expressed more elegantly and in far more detail by Bob Martin in Clean Code and countless other books and articles that predate it.

What about the ‘why‘

Jeff Atwood has already contributed his tuppence worth on this subject and I agree with a lot of he says. Apart one from one thing, he says that comments have a legitimate role in describing to the reader the reasoning behind decisions to implement a solution in a given way. I agree with him that it is difficult to express this information in code alone and that an additional enrichment of the code is required. I think he‘s wrong to say that comments are the best way to achieve this.

Version history and meaningful commit messages can better and more reliably express the reasons behind decisions made. I do this all the time in my day to day coding. If I see some code that I fail to understand the reasoning behind I look up the history of the file and read the commit messages. The code base I‘m currently working with has undergone a lot of change and few of the many comments that litter the code are of any use. Luckily, there is a wealth of information in the Subversion commits, some with references to issues in JIRA.

The commit messages are persistent and reliably associated with lines of code. They don‘t become stale and they don‘t become detached from their context.

Ugly

So there it is. Code comments are bad, they‘re ugly and they create more trouble than their worth.

More than anything, it‘s the ugliness I take most issue with.

If you‘re into software craftsmanship, then you‘re interested in elegant and (dare I say it) beautiful code. You‘re interested in code that tells a story, that expresses to the reader your intention. Essentially, this is code that documents itself. This sort of code does not need comments.

After years of riding a hardtail I recently bought myself a full-supsension bike. It‘s a 2005 Cannondale Prophet with 140mm travel, provided by a Lefty on the front and a Manitou 3-way Swinger on the back. It was hardly used, not a single scratch or any sign of wear, when I got it and I have to say I couldn't be happier with the bike. Already it almost feels as familiar as my hard-tail of 8 years, a 2002 Kona Caldera with 100mm Fox Vanilla on the front.

As happy as I am with my new FS bike, a few niggling doubts have crept into my mind about the benefits of riding a bike that bends in the middle.

Laziness

When riding a hard-tail, I‘m always carefully choosing a line. I‘m choosing a line that will maintain speed, set me up for the right line further down the track and most of all I‘m choosing a line that will not completely kill the rear of my bike. This is even more of a consideration when climbing because in order to keep the power down the back needs to be touching the trail.

On the Prophet, I can be far less picky about the terrain I decide to ride over. This seems good to start with, it feels liberating not to have to worry about the kind of bumps and drops that would make life on a hard-tail positively uncomfortable. But now, because I can give less consideration to minor undulations in the trail, I kind of feel I‘m losing some sharpness, losing focus, losing precision. I don‘t feel like I‘m learning anything new when I go out on the trail. I‘m still new to the Prophet and FS in general. Maybe these things will come back as – over time – I gain confidence and therefore speed.

Raising the stakes

Speed. Everything can be so much faster with a bike that bounces both ends. Again, I initially reveled in the capability to go faster on the Prophet over terrain that I know I would have to hold back on with the Caldera. A graze-inducing stack and a few sphincter tightening near misses a couple of weeks ago at the Marin Trail at Gwydyr Forest is bringing into sharp focus how, with that extra freedom, comes higher stakes. It‘s making me think about things like body armour and full face helmets. These are not comfortable thoughts to be having.

I‘ll be riding the Dyfi Enduro this weekend (2nd May 2010). I‘ve never done it before, though I have ridden some of the route on a different ride.

So will I be taking the Caldera? Hell no, the Prophet is way, way more fun!

I‘ve been adding some test coverage to some existing code today. This code under test uses Commons HTTP Client to fetch data from an external resource. I ran into problems with mocking/stubbing the response to the HTTP requests.

I am not the only one who has faced problems with this Http Client. In that article, Florin provides a good solution using a concrete subclass of HttpClient in order to mock it‘s behaviour. His article was very useful in helping me formulate my approach.

I use JMock for dynamic mock objects and so I was keen not to have to mix of JMock-based mocks and concrete mock objects. So my approach is to use JMock‘s custom actions to provide an implementation that populates the right values in the right way. Although, I had to use some reflective cheating to set the necessary values.

This is intended to be used as follows:

Now I can simulate all sorts of responses from the external resource.

The view of Llanberis and Snowdon from Fachwen. March 2010.