≡ Menu

Leave the Code in a Better State than you Found It

We’ve all been there: code that hurts your brain to look at, let alone comprehend.

Not written by you, of course. You wouldn’t write a mess like that, and you can hardly believe that somebody else did (or maybe you can…?)

Your mind wanders to who to blame for this abomination before your eyes. You start complaining to the person sitting next to you. Then to your boss. Then you decide that it’s time for a coffee and then to browse for new jobs.

Sound familiar? I bet it does!

The difference between an average programmer and a good one is in what you do next.

Do you ignore it and try to forget you ever saw it, or do you attempt to improve it?

I have a simple rule that I like to follow: I always try to leave the code in a better state than I found it.

This might involve small improvements, like improving code formatting, renaming methods or variables, or adding useful comments. Tiny improvements add up over time, especially if the whole team is doing the same thing!

Or the improvement could be larger, like refactoring or adding test coverage.

Yes, this can take time, and yes you do have that deadline to consider. But it’s amazing how quickly small improvements can be done; certainly in much less time than it took to understand that grotesque code. Which means that your improvement might make it much quicker for the next person to understand – and that next person might be you, when you revisit it in a year’s time…

The important thing is to do it, and encourage your whole team to do it. Don’t be afraid to change things. Take responsibility for that code, even if you didn’t write it: embrace collective code ownership!

{ 7 comments… add one }
  • Damien September 23, 2011, 10:52 am

    Dude some great advice there… I just did a job where I couldn’t bear to look at the code, so I refactored it to use industry standard design patterns… SOOOO much cleaner implementation, and made it so much simpler to read.

  • brendan September 23, 2011, 3:53 pm

    @Damien, nice work mate – and very good point about design patterns. (If Wordpress had a “Like” button I would be clicking it right now!)

  • Kane September 27, 2011, 10:06 am

    Hey Brenda

    Hopefully your refactorings (be they small or large) follow your companies code guidelines and more importantly SOLID development principles.

    However one trap many programmers (myself included) fall into is overusing design patterns or refactoring something that makes more sense just for them.

    For example I recently employed a developer who was technically very competent and decided to rename a whole bunch of variables, classes and methods because it seemed to make sense to him. The rest of the team however knew these classes and methods by their original name and caused unnecessary confusion. While no doubt the problem here has more to do with communication than improvement it does highlight a very important point. Remember to tell everyone or reach agreement if making significant changes which may affect others. Similarly the same guy (who no longer works under my team) over used the Strategy pattern and made something simple into something difficult for an average programmer to comprehend and maintain. Once again the problem here has more to do with communication rather than technology but the two have to work together to deliver a successful result that will be easier to maintain in the future.


    • Kane September 27, 2011, 10:09 am

      That would be … Brendan not Brenda sorry mate – blame the iPad.

    • brendan September 27, 2011, 1:29 pm

      Hi Kane, thanks, very good points well made. I’m glad somebody pointed out the assumptions inherent in my post!

      I agree: communication is key, especially when embarking on refactoring exercises. The value of such changes also need to be assessed; if the change doesn’t make the code easier to understand and maintain, then it may be subtracting value and just wasting time. The timing of branch merges should also be considered – a trap I’ve fallen into at least once (Resharper reformat whole solution, anyone…?).

      I think is useful, particularly for larger teams, to have a coding standards doc that all team members read and conform too – it can save everyone a lot of time (and short-cut a lot of arguments!)

      All changes should obey SOLID. I would also add that when refactoring (and in general) it’s also sensible for the code to have a solid set of tests before making the change – otherwise the risk/reward trade-off may be prohibitive.

      … and last but not least, enforced code reviews so that all the above is conformed to :)

      My post was a little simplified for easy digestion but it’s really great to discuss the caveats – perhaps another post is required?

      • Kane September 27, 2011, 1:58 pm

        Nah mate, enough said on this post – if someone needs more detail on the assumptions made within the blog then they should give up coding. I shall await your next post and see if I can add some value.

  • web design and development May 31, 2012, 8:38 am

    This is really great. I like to be visiting your blog. Thanks very much for sharing all this great information here.

Leave a Comment