TODO: Refactor this

Anyone who’s worked on a sufficiently large code base will have probably come across a comment like this one.

// TODO: Refactor this

No doubt left there by some well-meaning developer and probably ignored by everybody else since.

Sometimes it will be accompanied by a rant about exactly what’s wrong with the code in question.

Comments like this serve no useful purpose!

They may serve as a bit of a stress-relief for the person inspired to write it but other than that are a waste of time. If the person leaving it wasn’t inclined to do the refactoring then what makes them think someone else will?

Or maybe they optimistically think they can come back when they get some free time and do it. They almost never will find that free time – the comment will sit there until the developers on the team no longer even notice it anymore.

Here’s what I like to do when I come across some code that I think could do with some refactoring…

Consider working on it right away

If I have time and/or it’s in scope I’ll try to refactor it there and then.

If I can’t do it right away…

Raise a tech debt ticket in the bug tracking software

This creates an actionable task that can be discussed by the team and tracked.

Leave a TODO comment referencing the bug tracker number

This ties the code in question back to the ticket.

Add my name/initials to the comment

This gives people someone to talk to if they happen across the comment.

Oh yeah, and I save the rants for down the pub!

Visible Progress

A few weeks back I’d been sat at my desk at work reading Steve McConnell’s blog entry on building a fort and how it compares with software development.

It’s quite interesting how many similarities there are between a software project and an engineering project (of sorts) even though they don’t really become apparent until after the fact.

Steve even managed to make a “classic mistake”.

4. Substituting a target for an estimate.

I had 7 days to do the project, and my estimate turned out to be 7 days. That’s a little suspicious, and I should have known better than to make that particular mistake!

It shows that when we are outside of our problem domain it’s easy to forget what we’ve learned.

I had an object lesson in this later on that same day when I was thinking about some small project that is going on in our office.

We’re getting a shower installed at work, and as I’ve just started cycling into work I had been taking an interest in the work.

The work started the week before but I wasn’t getting too excited about when it would be done as I know these things can drag on and hit all sorts of snags and problems.

It’s like software right? You can plan and plan but some unforeseen problem is always waiting around the next corner.

So, I was quite excited later that same day when I walked past the shower cubicle to see the shower unit had been attached to the wall.

My immediate, almost instinctive reaction was that the shower was pretty much installed and I’d be able to use it by the end of the week.

I walked back to my desk feeling quite pleased when suddenly I realised that I too had made a “classic mistake”.

Joel Spolsky explains this problem quite succinctly.

If you show a nonprogrammer a screen which has a user interface which is 100% beautiful, they will think the program is almost done.

People who aren’t programmers are just looking at the screen and seeing some pixels. And if the pixels look like they make up a program which does something, they think “oh, gosh, how much harder could it be to make it actually work?”

The big risk here is that if you mock up the UI first, presumably so you can get some conversations going with the customer, then everybody’s going to think you’re almost done. And then when you spend the next year working “under the covers,” so to speak, nobody will really see what you’re doing and they’ll think it’s nothing.

I was acting like that client, seeing the “front-end” and assuming all the back-end work was done and/or didn’t exist.

I felt pretty silly once I’d had this realisation.

And it turned out that I was being silly as it still took a few more weeks before the shower was actually complete – of course, during that time the workmen were nowhere to be seen – but hey, it’s not like me to question the integrity of the great British workman.

“Source control ate my files!”

Everyone who has worked in Software Development for long enough must have heard somebody say that source control ate their files – it’s up there with “Works on my machine” and other such silliness.

Invariably source control didn’t eat their files at all – the problem boiled down to a (sadly) not too uncommon condition of “Fear of Source Control“.

Here are some of the symptoms of such a fear.

Unwillingness to do an update

I worked on a project years back with a tight deadline, not a huge amount going on in the way of process and about 6 developers all coding like hell.

Invariably, every other update broke your local build as someone had changed an interface or forgotten to check in a file (we had no daily build either), so yes, updating was a pain.

For two of the less experienced team members their solution to this problem was to hold off updating as long as possible (they’d happily go two weeks without doing an update).

When I queried their approach their answer was that doing an update “broke things” so was best avoided.

This symptom of course goes hand in hand with…

Unwillingness to do a commit

As anyone who has worked with source control systems long enough knows, they won’t let you commit a file if there are outstanding changes to be merged in.

So, leaving long gaps between updates almost always leads to massive problems when you finally commit your changes.

Long update intervals lead to long commit intervals.

My usual solution to this is to do an update every morning before I start any development work for that day.

Of course, I now work on much saner projects where things don’t break so often (or when they are likely to break things then someone has already warned you in advance).

That way I get the small amount of pain out of the way without huge disruption to whatever I am working on.

I then commit my work once it’s complete and passes its tests.

I also try to pay attention to what my colleagues are doing on the project too so I can avoid nasty surprises.

Deleting other people’s code

I have seen this happen, usually when someone gets a merge conflict.

Merge conflicts are what happens when two people work on the same code at the same time and the changes from one person’s work are merged into the other’s work.

Sometimes this happens smoothly and everybody is happy and sometimes not so smoothly and one person is very unhappy.

In the face of a merge conflict the correct approach is to fix the code by hand, which often involves talking to the other person who worked on the file to ensure that both their changes and your changes are preserved.

The incorrect approach (and yes, I’ve seen it done) is to remove the offending lines (someone else’s code), keep yours and commit away. This is of course a “bad thing”.

Merge conflicts are of course best avoided, even experienced developers strongly dislike them.

The way to do this is through communication with your fellow team members and knowing who is working on what area of the code (Scrum-like daily meetings are great for keeping up with who is doing what).

Often, said conflicts can be avoided by a bit of advance planning (you do your bit, test and commit, then they update and pick up your changes before they do their bit etc).

Commenting out unused code

If you’re lucky it will be accompanied by a vague comment along the lines of “I don’t think this is used any more” .

This stems from the fear of not knowing how to use source control to retrieve old versions of a file.

The correct thing to do of course is to remove it, then commit that change and mention said removal in the commit log.

If the code is being replaced then a comment along the lines of “Replaced foobar1 with foobar2 – foobar1 code lives in version 4.1.2 in CVS” would be most appreciated by future developers (which could of course be you).

Committing backup versions of files

I’ve just finished working on a project where a binary file that was kept in CVS had no less than 7 alternate versions (none of which were used) checked in alongside it.

I spent ages working out what each one did, seeing it did nothing, then removing it from CVS.

Again it stems from confusion and fear of using source control to get access to older verions of a file.

The solution

The solution to all of these problem is of course to “lose that fear” and learn to love your source control tool.

One good way to start doing this is to stop using a GUI to manage your source control tool and learn the command line instead (assuming your tool has that option).

That will remove a lot of the mystery of what is going on.

Learn the mechanics of your source control tool by reading the manual.

Eric Sink has an excellent series of posts on source control that highlight some of the many benefits of using it.

The final thing to realise is that correct use of source control will save your bacon.

The initial learning investment will be repaid time and time again.

And that, is worth its weight in gold.

Sit up and don’t slouch

I’ve just been trying out the suggestions on Jeff Atwood’s post on Computer Workstation Ergonomics.

I’ve known for ages that my seating position when at my computer is wrong; I’m a terrible sloucher you see.

Fortunately I’ve never experienced any back pain from it, so I’ve just carried on doing it.

But at the back of my mind I’ve always suspected that at some point I will experience some ill effects from it and I’ll regret my years of slouching.

So, Jeff’s post provided me with the impetus (and information) to do something about it.

Following the graphics and suggestions of Jeff’s site, I adjusted my chair (the only thing I can adjust) to match the ideal image (back straight, knees bent at 90 degree angles, eyes in line with top of monitor etc).

I’m in that position now as I type this post.

Some initial observations:

  • It feels strange, not uncomfortable, but I do keep getting the urge to slouch downwards – fortunately the new set-up pretty much prevents me from slouching and still being able to type at the keyboard.

  • I’m a little achy from spending much of the bank holiday weekend riding my new bike, so it’ll take me a few days to determine if any aches and pains are bike related or chair related.

  • I’m finding new reasons to learn to touch type! One of the guidelines is to use my chair armrests to support my elbows – for me this means that my left hand can only comfortably reach the left side of the keyboad, and vice versa for my right hand. What I am finding now is that as I type, sometimes my left hand instinctively tries to press a key on the right hand side of the keyboard (and vice versa, I type with both hands), which means that my arm then lifts off the armrest. I need to learn to touch type properly so that my arm doesn’t have to lift up.

  • My left elbow no longer hurts from resting on the (stupid) curved desk – woohoo!

I need to do the same at home now, and then monitor the situation long term.

How to mentor programmers

I was reading an entry over at Raganwald where the author talks about managing projects.

He covers a list of things that one should try to do to ensure a project is a success.

One of his main points is that a tech lead should always know exactly what everyone is doing on a daily basis.

Whenever I’ve allowed the details of a project to escape me, I’ve failed. […] And I can tell you, whenever the details of a project have slipped from my grasp, the project has started to drift into trouble.

I’ve been the tech lead on many projects over the last 6 years or so but I’ve always stopped short of asking people what they are doing on a daily basis.

It has always struck me as a form of “micro-managing”, which is something that I’ve hated when I’ve been on the receiving end of it.

I should clarify though; I always know who is working in what area on a day to day basis (Jim is working on the email module for these two weeks), but I don’t necessarily know what specific task they are trying to achieve on a particular day (I don’t know if Jim is writing display code today, or back-end logic).

However, after reflecting on how this has worked on my projects, I have to conclude that my approach was wrong.

I should know what people are doing – I just need to find a balance between knowing what they are doing and getting on their nerves.

Clearly a balance can be found.

I make no apologies for now insisting on knowing exactly who, what, where, when, and why. There’s a big difference between being asked to explain your work in detail and being told how to do your job.

I’m not sure of the best way to handle getting to that level of detail though.

Daily meetings where everyone reports progress?

I find these to be a bit of a waste of time (especially in large teams) where you talk for 2 minutes then sit and listen to everyone else for 20 minutes.

Walking around and sitting down next to each person in turn (sort of like a Doctor doing his rounds)?

This is better for the team as they are only interrupted when I am talking to them.

I’ve done this before but never in a “tell me what code you are writing now” way.

I still think this might annoy me if I was on the receiving end of this.

Another way?

What about other tech lead people reading this, what works for you?

Or, if you’re on the receiving end of this, where exactly does that all-important line sit?

Client presentations

I attended a client pitch yesterday.

As in, we were pitching to a potential client.

I had to stand up and waffle on about technology choices for ten minutes.

Needless to say I was terrified beforehand but when I got up there it all went reasonably well.

As a programmer I’m not really comfortable standing at the front of a room talking in a loud voice while everyone looks at me.

It took some degree of will power to force myself to get up there and project my voice.

I had some print outs of my slides with notes all over them, but I ended up not referring to them at all – I pretty much remembered everything.

I rushed through one or two parts a bit too fast, and got stuck where I couldn’t explain “session migration” without using the words “session” and “migration” (this was to a largely non-technical audience).

I also didn’t make enough eye contact apparently.

Some things to improve on then, and next time (if there is a next time) I won’t be anywhere near as nervous.

I did manage to make them laugh though, which is always a bonus.

And the moral is…

Salesman: “Just give me a quick finger in the air number for how long it will take to build this, I won’t hold you to it!

Me: “You won’t hold me to it? Ok, this much“.

2 months of requirements gathering, speccing and estimating later…

Salesman: “Can you please explain to me why these costs have doubled?

You couldn’t make it up.