Comments revisited

About a year ago I wrote an article on comments.  That article left me feeling uncomfortable.  In it I made a point that people may think that their code is too simple to need comments.  Indeed, it is not beyond the realms of possibility that this is in fact the case.

I’ve been reading a book called “Clean Code – A Handbook of Agile Software Craftsmanship” by Robert C “Uncle Bob” Martin.  He devotes a whole chapter to comments – which is highly commendable.  His thoughts on comments can roughly be surmised by the following extract:

The proper use of comments is to compensate for our failure to express our-self in code. … We must have them because we cannot always figure out how to express ourselves without them. …  Every time you express yourself in code, you should pat yourself on the back. Every time you write a comment, you should grimace and feel the failure of your ability of expression.

Despite my earlier post, I have reached the conclusion that I agree with him!  Indeed, the argument “My code is too simple to need comments” should describe the code you are aiming to write.  Being objective in your analysis of your code is the hard part.  Martin’s main objection to comments is what I was alluding to in my earlier post:  they tend to “rot” by becoming less reflective of reality over time if not maintained along with the rest of the code base.

A lot of the early chapters of Clean Code revolve around the “common-sense” aspects of coding. 

  • Variables should be descriptively named (as should functions and classes)

  • Functions should do one thing and one thing only.

  • Functions should be short. (In fact, as Uncle Bob puts it: “Make a function short, then make it shorter”)

The second strategy I recommended for writing comments was to “pretend you were explaining the block of [complex] code to someone else”.  As Martin states, this is a failing of the code.  You would be better off refactoring the code so that it wasn’t so complex.  If you apply the “common-sense” aspects of coding, you will probably find that your complex code violates at least one of the rules.

I was pleased to see that Martin suggested that comments were okay when written to convey the intent of the author.   This is still my number one use for comments. 

It’s been an interesting read so far and I am sure there will be other topics that I wish to reflect on in blog form.  Expect to see more in the coming weeks!


Indicate your intentions!

I saw it again this morning…  A motorcyclist blissfully unaware of an indicator left on.  I wouldn’t know how many accidents this action causes.  Maybe not many – but any number greater than zero is too many.

Most modern motorcycles have standardised on indicator switch configuration*.  Operated by the left thumb, a self-centring switch can be pushed left or right to activate the turn indicator and pressed in (into the switch-block) to cancel the indicator.  For many years, BMW have done things their own way, in an effort to confuse motorcyclist journalists and test-riders alike.  For their new models appearing next year, it looks like they have finally relented.  Huzzah!

Indicators on motorcycles don’t self-cancel.  Like so many aspects of riding a motorcycle, the onus of responsibility is on the rider.  If your indicator is signalling your intention to leave a road, it is reasonable to presume that some drivers will actually expect you to do just that.  The possibility of a driver (or rider) pulling out in front of you has just increased.  Most drivers paying sufficient attention would probably detect that you are not likely to be taking the corner due to your speed, body language or lane positioning; but do you really want to rely on them paying attention?

When I learnt to ride, one lesson was passed on to me by a qualified instructor that I feel is justified in mentioning here.  Make a habit of pressing the cancel button on your indicator every now and then.  If you’re not indicating, it does nothing – but if you are, of course, it stops!  There is a tactile difference when pressing the indicator cancel button when the indicator is actually going.  From time to time, I’m surprised to find that I’ve left my indicator going longer than intended.

* As a funny “aside”, I once rode a friend’s Aprilia Tuono.  On my Honda, the horn button was directly below the indicator button, whereas on the Aprilia, it was directly above.  The end result was after every corner we went around, we ended up blasting the horn! (And yes, I blasted it a couple of times when performing my “redundant cancel” habit too!  To cover for excess horn usage, just wave at somebody as if you know them!

Don’t mock me!

The framework on which I predominately work on has used a “nightly build” script for longer than I care to recall.  While the new cool kids on the block have turned to techniques such as continuous integrationwe still rely on the build “once-a-day” technique, or manually kick off the process when required.

Way back when we established our build script, one of the developers created a testing framework with which we could perform unit testing.  It was no jUnitbut it performed a similar role.  Our team wrote some unit tests in a slightly less than committed manner and we felt good about the whole process…

That trusty in-house utility has served us well over the years and we still add unit tests to it, but the whole concept of unit-testing has matured a vast amount from where it was when we originally set off along that path.  Realistically, some of our unit-tests would more accurately be described of as integration tests – that is, they are testing the interaction of two real classes.  This isn’t a problem in itself, but it is not an area that unit testing is meant to be testing… 

My current “side project” (read “train-time project”) has therefore been to change our unit-testing application over to an xUnit framework.  I could have left the legacy framework as part of the build script and built a second testing framework for all new test-cases, but fortunately the underlying interfaces that drive the xUnit implementation are similar enough to allow relatively painless migration of our existing tests into the new framework.

With the existing test-cases migrated, I turned my attention to the development of new test-cases.  Not wishing to repeat the mistakes of yester-year, I did a little research on “mock objects”.    As one presentation suggested, I googled “mocks aren’t stubs”.  At this point in time, it is safe to say I am not an expert in writing unit-tests.  I have done them, I can see their worth and I’ve no doubt it doesn’t take a lot to get competent at writing them, but I’m still learning. 

So as a really rough approximation of what the mock objects can do for you:  They allow you to exactly define what things you are expecting the mock object to be used for in your unit-test.  How many times a function of the mock object is used, what parameters it will be called with and what return values it should give.  This helps give you an extra set of conditions by which you can verify that your code is correct. 

One thing that strikes me as “odd” about this level of checking is how you are ever meant to change your code again without needing to modify the unit test.  As the verification of running your unit test includes specifying exactly how your code interacts with other objects, it would seem to limit the changes you can make.  Maybe that’s the point!  I’ll tell you more, when I work it out!


Valentino Rossi

Valentino Rossi

When you look at the regular riders of the MotoGP this year, you find what can only be described as a “class act”.  Of the regular eighteen riders, eight have won world championships in the various classes, and that’s not counting the rival World Superbike Champions currently riding in the  MotoGP series.

From the earliest races, it was apparent that there was an upper echelon of riders this year.  Four riders looked like they would fight for the championship all year: Jorge Lorenzo, Daniel Pedrosa, Casey Stoner and Valentino Rossi.  These riders didn’t have top billing rites to themselves this year.  There were standout performances from other riders as well.  As the season progressed, the challengers started to fade away, leaving the two protagonists from last year (Rossi and Stoner) to resume their on track rivalry.

It is typical of top-level sports performers, that injury plays a major part in the “luck” department.  The risk of injuries in motorcycle racing is far more apparent than some other sports, but from a spectator’s viewpoint, the result is the same:  An injured sports-star cannot perform at their best. 

The first of the four contenders to “fall” was Jorge Lorenzo, with not one, but two spectacular (and painful) “high-sides”.  High-sides* are (thankfully ) rare these days.  The smoother power delivery of four-stroke engines and the advent of traction control systems reduce the times you will see a rider “sail” through the air.  Regardless of rarity, Lorenzo managed two of these accidents, sustaining injuries  and clearly denting his confidence in the races that followed.  

Pedrosa “faltered” next, his championship aspirations being dealt a fatal blow when he fell whilst leading the rain sodden MotoGP in Germany.  In the second half of the season, the other two riders (Rossi and Stoner) were simply a class above the rest of the field.

Casey Stoner looks to be a rider with sufficient talent to see him become one of the true greats of the sport.  At numerous times in the last two seasons he has simply been the fastest rider out there – by a long way.  At quite a few races he has dominated every practice session, every qualifying session and every lap of the race.  That the Ducati he rides is fast, is beyond question – but you need only look at how incompetent the other three Ducati riders have looked this year to realise it’s not just the bike! 

This year’s champion elect is none other than Valentino Rossi.  As in all sports, comparisons against competitors from previous years can be nothing more than speculation.  Statistically, he is already second in terms of “premier” class world-championships and first in “premier” race victories.

Whether or not he is the greatest racer ever will be the subject of much pub-debate for years to come.  In my mind, he is the ultimate racer, for the following reasons:

  • He is a fierce competitor.  Even where a podium would suffice to seal a world championship, I can’t think of one instance where he has settled for a place rather than push for a win.

  • He appears to be instrumental in improving the performance of the bikes he has ridden.  Developmental riding of a racing motorcycle is an undefined and rare skill.  Not many riders do it well, but the success of the bike manufacturers seems to follow Rossi.

  • He is a sponsor’s delight.  He is thoroughly charismatic and consistently “clowns around” for the amusement of others.

  • He is driven by the challenge.  He swapped teams when winning on a Honda became “too easy”.

One point which is often overlooked about Rossi’s most recent World Championship, but is telling about his competitive nature:

There aren’t many riders who win a world championship, then lose it, who come back to win again in later years.  I think the last rider who did this was Giacomo Agostini  


* Most single bike racing accidents fall into two categories:  A “low-side” is where (normally) the front end of the motorcycle “washes out” from the bike.  The bike and rider fall down – on the side that the bike was leaning.  This is roughly the equivalent to a car “under-steering”.  A “high-side” typically occurs when the rear-end of the motorcycle runs-wide.  This tends to happen when the rear-wheel spins faster than the front.  (Roughly the equivalent to a car “over-steering”).  The immediate human reaction to the rear wheel “stepping out” is to back off the throttle.  The problem with this is the rear tyre can suddenly start to grip again and the bike is thrown violently upwards as it does so.  Where this happens the rider is thrown over the “high-side of the bike”.


Photo courtesy of: Kyn Chung released under a Creative Commons licence.