Category Archives: Computing

Making comments worth their weight in diskspace.

No matter which language I’ve written code in, the one common feature has always been “the comment”.  Usually comments are described in the language definition along the lines of “ignored by the compiler”.  Given some of the code I’ve seen, I could almost extend that definition as “ignored by everyone”.  It shouldn’t be this way people!

Like most of the problems / issues I see in the computing industry, the problem here is one relating to poor communication.  Better communication invariably leads to better collaboration.  Code comments are under-rated.  Whenever I have read texts referring to when and where to use comments, they have seemed to come up short.  Most texts will tell you to avoid making obvious statements and instead use them to explain complex logic.  The problem is, when you are coding “in the zone” even the most complex multi-threaded, recursive algorithm seems straight-forward. 

The first mistake when writing comments is therefore defined as “My code is too simple to need comments”.  AKA “Anyone can read the code and determine what it is doing”.  In this regard, you’re probably right!  Most decent programmers could look at your code and determine what it is doing. But is that what you intended it to do?  

The second mistake with comments is using them to comment out code.  This practice is okay when you are debugging code, but no completed work needs a “dead code museum”.  Revision Control Systems are perfectly adequate for keeping a log of how the code used to look.  You do use a Revision Control System, don’t you?

The final mistake made with comments is ignoring them.  Over time, code changes and as such sometimes comments written will no longer accurately portray the code it is written about.  If you see an inaccurate comment, FIX IT

As to how to write effective comments, here are two strategies to try.

  1. When writing a new function, start by writing the comment.  In this comment, list the steps you will use to solve the problem.  Then write the code, breaking the single comment up into multiple ones, interspersed with the code needed to perform the action as defined by your comment.  When you’re finished, you should have a good suite of comments guiding the next developer through the thought process you used to solve the problem.
  2. When altering existing code, put in a “placeholder” comment whenever you look at a block of code and wonder what it is doing.  Once you’ve got the placeholders, go back and pretend you are explaining the block of code to someone else.  Listen carefully to yourself, because there’s your comment.  Remember, that bug finding is so much easier when a decent comment describes the “intent” of the code, rather than what the code is doing.

Whilst there may be other good strategies to use when writing comments, starting with these two should see you off in the right direction.  If you’ve got any other pet advice on what makes a good comment, feel free to leave me a comment on this post!

Quality takes time

I have to admit: I am not the world’s fastest programmer.  Actually, it is probably fair to say, “I’m not the world’s fastest at anything”.  But when it comes to programming, I consider this to be a blessing far more than a curse. 

When writing code I find myself doing a rough draft first.  I then “reboot” my brain and look at the code again.  Now comes the tidy up: “Is there a simpler way of writing logic expressions?”   “Are the variable names expressive but succinct?”  “Are there comments explaining what I was aiming to achieve with the code?”  Over my years in the industry, I’ve witnessed times when what I would consider to be the rough draft is what is committed to the Revision Control System and the task is declared complete.

If the biggest difference* between draft and final version are things like formatting, variable naming and additional comments, is the code really compromised by submitting it in “draft” format?  Yes!  Long term maintainability suffers and this matters.  Once bad code is committed to Revision Control, it is very difficult to remove.  It takes a brave (or foolish) developer to cut swaths of “working” code.  In a large system, you end up with areas of “bad code” akin to an ancient burial chamber.  Daring to upset the artefacts in there will likely end up leaving you cursed and release untold horrors upon the world.  Good code is more akin to a well lit and ventilated room – you can see what you are doing and there is little threat of initiating the apocalypse by altering the contents of the room.

Don’t underestimate the damage that hastily written “draft” code can cause.  The impact of creating a maintenance nightmare is that bugs in this code can hide forever.  If you think of your technical support department as a group that charges the company every time a bug is reported, you will understand why having bugs is a bad thing.  Well, guess what?  Every time a bug is reported, it is costing your company money. 

What I am suggesting is that it’s OK not to be fast.  There is always a competitive need driving your “time to market”.  When analysed, most disciplines exhibit some form of compromise.  When writing software, this compromise is often the trade off between quality and time taken.  In other words, it’s a balancing act. In my opinion the best developers know almost intuitively how (or rather when) to make this trade off.

* Quite often code simplification arises out of the second look.  That’s always going to be worth it!

Avoiding Feature Bloat – Making the “good idea” better

Commercial software development is the art of creating sustainable revenue from a “good idea”.  Once upon a time, someone thought: “Wouldn’t it be good if there were a program that can do X?”.  Being the cunning entrepreneur / thrill seeker or in some other way just blind to the possibility of failure, this person then set about writing such an application, confident that because they wanted it, other people will too – and that those “others” will part with their hard-earned cash in order to get it.

In order to keep the sales ticking over, this idea expands with upgrades in an effort to keep enticing people to pay up.  Keep making it better, keep people paying…  The only problem is defining “better” for software is somewhat vague.  You can add features, or you can fix bugs.  Adding extra features treads the dangerous path of spoiling the software and according to Bill Gates, no-one wants to pay for fixing bugs.

In other words, there’s no defined science as to how to make the software better, but there’s plenty of circumstantial evidence that you can make your product worse.  The good ideas for your product are out there, but they are well camouflaged and hidden amongst the myriad of worthless potential features.

Dawn Foster is of the opinion that:

“Open source software seems to be better at figuring out which features are really needed by most people and not getting into the trap of trying to satisfy every need that a potential customer might someday have.
By providing the source code, open source software often avoids feature bloat. The source code gives a customer with a specific need the flexibility to add a feature.

It boils down to this. When considering feature bloat, open source software has an advantage over proprietary software because the source code provides more flexibility to the user community. Users can choose to add features and functionality as needed without relying on a vendor to satisfy their every need.”

However, it is worth remembering that the “good ideas” will come from a specific need.  This was what spawned the product in the first place.  But often, once the product is released it ceases to be “your need”.  “Your need” becomes a way to track and prioritise feature requests, bug reports, sales leads etc.  Basically, everything but making the software better.  This is the true advantage of the open source movement.  They aren’t interested in making money from an idea, so they remain faithful to their original need.  Often there is no communication gap between vendor and customer because the vendor is the customer – so the “needs” remain undiluted.

Adding features for the sake of it, will reduce the overall appeal of the product.  Commonly this sort of bloat leads to a performance drop off in the software but even if you can avoid lowering the performance of the software you can end up with a situation of more features = more complexity = more confusion = less customer satisfactionRob Goodlatte writes

“Bloated software is harder to sell. Marketing messages become diluted when theres (sic) too many features for too many types of users. Don’t extend software with features that stray from the original vision – both brand and product will suffer.”

Given that you need to eat and you’ve elected to make money from your “good idea”, the question then becomes: “How do I avoid straying from the vision?”.  I think you need to be of the conclusion that sooner or later your software will be “perfect” in terms of a feature set.  Perpetual motion doesn’t exist, so stop trying to write software thinking that it does!

This idea leads to several others:

  1. You won’t need to be forever looking for a useful feature to add.  At some point you will say that everything worth doing has been done.  The idea here is simply to avoid adding the bloat in the first place.
  2. At some point development of the product will be scaled back.  You are not euthanising the project – just re-prioritising resources.  Some market impetus may mean that in future you need to revive your program, so keep it on life support!  Regular bug fixes may not be a way to impress a new customer but you will be buying good-will from your existing customer base and reducing the burden on your technical support team.
  3. Creativity will not be restricted to only improving existing products.  The development team will recognise that their creativity should not be restricted simply to the product you are currently writing/selling.  The software industry is constantly changing and so should your product offerings.

Having said that, most software products are likely to have several (useful) ideas that will lead to upgrades.  Initially, these ideas will likely be features you wanted to put in to version one, but didn’t have the time or resources to do so.  Seeing this was your need to begin with, these ideas for upgrades are likely to please your customer base and are therefore worth doing.

After your initial crop of ideas run out, you are likely to turn to your customer feedback.  But who should you listen to?  I think Michael from “37 signals” is on the right approach:

“So what do you do with all these requests? Where do you store them? How do you manage them? How do you track all these requests? You don’t. Read them and then throw them away.

Yup, read them and throw them away. The ones that are really important will keep bubbling up. And those are the ones you’ll remember. Those are the important ones. You don’t need to track or remember everything — let your customers be your memory. They’ll remind you.

So, ask for requests, read the requests, listen to your customers, and then forgot what they said. Let them remind you over and over and over again. That’s how you find the real gaps in your product. That’s how you’ll remember what new features are really worth considering.

And one more thing: it’s not just about the sheer number of requests (we don’t recommend adding something just because X# of people requested it), it’s about customers planting a seed in your mind. If they keep reminding you of something, it forces you to think about it. Maybe it is a good idea. Maybe it isn’t. But at least it’s important enough to consider if so many people keep asking for it.”

It sounds harsh, but I think the idea is on the right track.  Personally, I am a little too conservative to just forget about the ideas.  I think the attitude should be to “log the requests, then you can forget about them”.  Storage space is cheap and having an electronic brain to quote the customer verbatim may be useful when determining exact requirements at a later date.  Of course, the catch is you will need to be able to find them again – but that may not matter:  I heard a story that Bob Dylan keeps all his lyrics in a book that he has with him on stage – in case he forgets the words to one of his songs.  If he ever needed it mid-song, he’d be in trouble of course, but he finds it reassuring to have… 

If you are going to use the “wait until you keep hearing the request” strategy to drive feature requests, then I urge you to remember the first word. “Wait”.  Good ideas take time, good software takes time, quality takes time.  But that’s a topic for another day. 

Hello world!

I’m new to this blogging game and don’t intend on making a huge habit of it.  I will be aiming for one post a week.  But I am a realist, so I guess what that means is don’t be surprised when I fail in this objective.  The two areas where I feel opinionated enough to write down my rants and express myself are quite disparate: Motorcycling and Computing. 

I’ve read that one of the key elements to a successful blog is to introduce yourself to your audience.  I’m using my first post to do just that!  My name is Andrew Napier, I live in Queensland, Australia and I am a computer programmer / nerd / motorcyclist (not always in that order).

As I’d like to include a picture in my first ever post, and me typing away on my laptop is not exactly enthralling, I will leave you with a shot of me and my wife on my current motorcycle, a Honda VFR 800.

The bike a mere 24hrs after purchase!