Tom Butler's programming blog

Put the pro in programmer: A guide to writing better code

Sometimes students who've completed the university course I teach and people who've finished my book ask what next?.

This series, partially inspired by the format of Misko Hevery's Guide: Writing Testable Code, is an answer to that question. Like Misko Hevery's reviewers guide which offers an excellent checklist of things not to do, I'm going to give you a checklist of milestones and hazards that you'll encounter during your programming career when you're transitioning from intermediate to advanced then professional level.

One of the problems with learning anything is that the more you learn about a topic, the more you realise you don't know. I wrote my first lines of code back in 1998 and I'm still learning today.

I'm going to split this into two distinct sections:

  1. Hazards Before moving on to changes you can make to your code to make it "better", I want to offer some general advice about improving as a programmer. There are several hazards that significantly slow down people's progress before they write a single line of code. Some people get stuck in them forever.
  2. Milestones you'll reach while progressing through your career. There are points at which you'll realise you need to rethink your entire approach. Think of them as eureka moments. After you reach one of the milestones your code looks a lot different than it did before. You'll look back at code you wrote previously and wonder what the hell you were thinking.


Hazards are flaws in your approach to learning or mental barriers that get in the way of your progress, preventing you from improving the code you write. If you get stuck in one of these hazards you'll keep writing the same code forever and progress at a glacial pace if at all. Many people end up stuck in one of these mental blocks forever.

Each one of these hazards are things I've gone through myself and seen others fall into. Hopefully by sharing my experience I can help you avoid falling into these hazards and it wont take you 20 years to reach the same conclusions I have today.

When learning about new programming practices you may fall into one of these hazards:

  1. Hazard 1: 90% of everything is crap

    Warning signs

    • You read articles that explain how the practice can be implemented but not why, where and when it should be used.
    • You look at the practice in isolation without weighing it up against alternative approaches
    • You read articles that are written by people who don't understand the subject much more than you do
    • You pay attention to someone just because they are experienced

    More >

  2. Hazard 2: But I've always done it this way

    Warning signs

    • You ignore new approaches because they are drastically different to what you're used to
    • Consider new approaches wrong, confusing or too much work because it requires a radical change to the way you approach writing code
    • You consider how much work it will be to implement the practice in all your existing code rather than considering it on its own terms
    • You don't want to admit the hundreds of thousands of lines of code you've written in the past could be improved

    More >

  3. Hazard 3: COOL!

    Warning signs

    • You rush to implement a new technique everywhere
    • You don't consider where or even if it is applicable
    • You are blinded by the novelty and fail to see any potential downsides of the approach

    More >

  4. Hazard 4: You are not clairvoyant

    Warning signs

    • You write code that cannot be used on a different website without modifying a single byte in the file
    • You assume code you write does not need to be changed in the future
    • You write code that logic that's useful on multiple projects with logic that's only useful on the website you are currently working on
    • You assume you're not going to need to do something

    More >


Milestones are radical changes in the way you approach programming. When you reach one of these milestones your code looks drastically different than it did before. Every developer goes through a similar process. You might reach these milestones in a slightly different order but each milestone you move through increases the quality of your code by a very noticeable amount and each time you reach a milestone your code looks a lot different than it did before.

  • Milestone 1: Everything belongs in a class
  • Milestone 2: Everything should be private
  • Milestone 3: Static is bad
  • Milestone 4: Inheritance sucks
  • Milestone 5: Inversion of Control
  • Milestone 6: Unit testing
  • Milestone 7: All tight coupling sucks
  • Milestone 8: Everything should be immutable
  • Milestone 9: ???

I eventually plan to give guides on reaching each of these but for now, at least you know what to look out for.

90% of programmers are crap

Don't fret if you haven't reached most (or any) of these, it took me an average of 1-2 years to move between each milestone. But I didn't know what my next milestone was going to be or have any direction on where to go next beyond running into problems with my current approaches while keeping up with interesting blogs and discussions. The main reason I'm writing this is to give you a direction to aim in.

If you have a basic knowledge of Object-Oriented Programming you are ahead of probably 95% of people who write code for a living. Most programmers spend their entire career writing spaghetti code for awful frameworks like Wordpress, Joomla or bespoke corporate systems, cutting and pasting chunks of code from StackOverflow day after day. Partly this is down to people getting stuck in hazards, partly it's down to tight deadlines and overpromised projects that offer little time for programmers to learn and improve.

If you're not at Milestone 1 yet, there are plenty of resources to get you there. Of course I strongly recommend my book which will give you a good grounding in OOP.

Most developers eventually fall into one of the hazards and get stuck at a milestone permanently and find themselves writing the same kind of code for years without any improvements.