Always remember to KISS!

At one stage in my career, I had the good fortune to be Team Lead for a group of immensely clever developers.  Once you get over the fact that you are probably the dumbest one on the team, this is an extremely fortuitous role to find yourself in.  Each of the developers had unique traits that complemented each other well and as a team I felt we achieved a great deal. 

There were three things I noticed when leading this group of developers.

  1. Smart people enjoy being clever. 
  2. One person’s clever idea, can be another person’s good example of “how to be obtuse”.
  3. Smart people don’t always realise how much they have to dumb-down their ideas before mere mortals will “get it”. 

Now read the above three points, substituting the word “idea” for “code”… Joel Spolsky talks about how the best developers are “smart and get things done“. As a developer, I think it’s a worthy goal to aspire to.  Certainly, much better than aspiring to be “stupid and achieves nothing”.  But don’t let your ego get in the way.  If you think you are good, you’re more likely to rest on your laurels, and in this industry, you should always seek to improve.

Sometimes people’s cleverness works against them in computing.  They fail to see the obvious solution and instead invent a complex and overly elaborate approach to a problem.  Quite often, this approach would map well to how a person would best solve the given problem.  Computers are not human. A university lecturer I once had described computers as “high-speed idiots”.  When you think about it, that makes them the opposite to a clever programmer. 

So, when writing code, remember the “high speed idiot” you’re giving the instructions to.  Don’t give it a complicated set of instructions to follow, thinking that some fantastic optimisation you thought of will be the difference between success and failure – chances are, it won’t!  Instead, you’re likely to create a maintenance hell, full of little caveats that allow for edge conditions you hadn’t originally thought of.  Keep the original KISS principle in the forefront of your mind when writing code! 

There is a certain irony in this tale.  I was midway through writing this piece, when it dawned on me that one of my side-projects was an exact violation of the KISS principle.  The worst thing about it was that the program was slower than if I’d done it “the simple way”.  But on the positive side at least I proved my own cleverness – if only to myself 😉

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!

Don’t take my word for it!

Let’s get one thing straight.  I am a computer programmer.  It’s what I do for a profession.  I am not a motorcycle mechanic, nor am I a motorcycle instructor.  My comments on motorcycling, and any mechanical advice should be taken as “just someone else’s opinion”. 

If you choose to follow my advice, you do so at your own risk! 

It is your responsibility to seek out the proper opinion of professionals.  By reading my blog, you agree to indemnify me from any civil or legal action arising from any damage to you, your belongings or any third party.

Fitting Leo Vince exhausts to a VFR

Before we proceed, please read my disclaimer

As far as mechanical skills go, if you can assemble Lego, or maybe an IKEA desk, then you will be able to install your own pipes on the VFR.  Here’s a walk-through of me fitting my Leo Vince pipes.  I would describe the process as “easy” and if your bike has never witnessed you holding a spanner, then this is an ideal first project.  I’ve written this walk-through in a fair amount of detail to try and give the wary and mechanically timid a good indication of what they will be up against. 

You will need:

  • One sixth generation VFR.
  • One set of Leo Vince exhausts.
  • One 3 mm Allen key
  • One 5 mm Allen key
  • One 6 mm Allen key
  • One 13 mm Ring spanner (or “wrench” if you speak with a funny accent)

Optional stuff that can make the job easier:

  • WD40 (or similar)
  • Needle nosed pliers
  • Small flat head screwdriver
  • Multi-grips
  • Spirit level

So, here’s the bike in question, in stock trim:

And here’s what you (should) get in the box. 

The exhaust even comes with its own miniature coat hanger!

Trap for young players: Ensure you have all the parts and tools required before pulling your bike apart – especially if it is your only means of transport.  Having to put everything back together half way through so you can go source extra pieces can be quite annoying!

I was very impressed with the overall build quality of the Leo Vince exhausts.  All the insides of the pipes appeared to have been machined and there were no welding dags in the joints etc.  The fit and the look were also first rate.  Having said that, there was one shard that was in the splitter pipe which was easily removed with a pair of needle nosed pliers.

OK Let’s get going!
First job, remove the seat and grab rails.  – There are plastic caps covering the four 6mm Allen key bolts.  Once these are removed the grab rails lift straight off.

Now, there are four Allen key bolts holding the duck-trail to the bike.  Two mounted horizontally near the front of the duck-tail (where the pillion peg bracket mounts to the sub-frame) and two mounted vertically just near the grab rail handles.  The duck-tail also has two plastic pegs seated in rubber grommets meaning it needs to be pulled straight back.  Undo the four bolts and slide the duck-tail straight back a few centimetres.
This gives you room to disconnect the turn signals, brake, tail light and licence plate light wires at their junction points.  (You should do so now)

Trap for young players: Never use force to pull wiring plugs apart.  There’s often a clip that is easily prised up with a flat head screwdriver.  If you’re having to force it, you’re probably doing it wrong!  If the bike is in poor condition, consider using WD40 spray on the connectors before attempting to disconnect them.

Now remove the rear fender.  There are four bolts accessed from the top and two accessed from underneath the bike. 

Tip: You may find it makes life easier to remove the right pillion peg and bracket.  This is held in place by two 8mm allen key bolts

Now the fun begins.  Loosen the clamp bolts at the bottom of the exhaust pipes where the pipe joins the catalytic converter.
Then remove the two bolts where the mufflers attach to the subframe.

Tip: If you can’t get enough leverage on the allen key to turn these bolts, you can use a ring spanner on the end of the allen key.

Carefully lower the pipes (remember that they are still attached to the catalytic converter) 

There’s a graphite gasket that seals the pipes to the catalytic converter.  This is what is currently holding the pipes on.  With enough care, you should be able to wiggle the pipe free without damaging the graphite seal, but remember that it is extremely soft compared to the metal its attached to.

With a bit of wiggling the pipes come off:

Hmm… must remember to check the car tyre pressures at some stage…

Fit the Leo Vince mufflers and pipes loosely.  They were all a good fit and didn’t require any silicon to seal them.  Leave everything loose to allow for minor adjustments. 

Don’t worry too much about getting things level yet.  We need to attach the springs first. 

(See it was a spring puller, not a coat hanger!)

Near as I could tell, the short spring goes to attach the left muffler to the pipe. 

All the other springs are the same length and secure the various join pipes together.

You can rest a spirit level across the pipes to make sure they sit level.  But if you do this, check that the sub-frame is level too! (in case you are on a slight slope and the bike is leaning)

The roly-poly cat thought I might need a supervisor…

…but quickly tired of the role and went to do something more interesting, such as stare at the wall:

Attach the supplied carbon fibre heat shield.  There were four soft washers and four metal washers.  The soft washers protect the finish of the carbon fibre and the heat shield.

Once you’ve got the set up level, tighten up the brackets and clamp and reassemble the bike.

No dodgy home-job is complete without having bits left over:

The bracket is meant to help secure the pipe to the pillion peg bracket.  But there was no way it was going to reach.  I could have futzed around with positioning the pipes such that it did, but the pipes would not have fitted so neatly and not without putting undue strain on the rest of the mounting points.  So, it stays off for now until I custom make a bracket, or modify this one to suit.

Edit: In case you were ever following me and frightened the exhaust system would fall off; you will be pleased to know that I have used a round file to elongate the hole in the bracket.  This has allowed me to use the bracket to help secure the exhaust to the pillion peg bracket.  To keep the pillion peg bracket square against the sub-frame, I needed to use an additional washer on the front bolt.

As far as I could tell, the four alloy spacers were meant to replace the standard rubber mounted ones where the pipe clamp bolts attach to the sub-frame.  The rubber washers were glued to the sub-frame and no doubt help dampen any vibration that travels through the sub-frame.  The standard set up didn’t seem worth disturbing.  The fitting instructions were very generic and the picture supplied was so small, it was useless.  However, even without IKEA quality instructions, I would still rate the job as “easy”.

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.