Code Renaissance is about building great teams and great software. By exploring best practices, team interactions, design, testing and related skills Code Renaissance strives to help you create the team and codebase that you've always wanted.

Brown field software: The five rules of code maintenance

As previously described (picture a cow pasture) brown-field development is the maintenance of an established project after the initial developers, working under tight time constraints, have pooed all over the place.

Photo by Fabio Rava

With that in mind here are 5 simple rules to help you clean up your code base:

  • #1 - Always leave the code cleaner than you found it.

    This is both common courtesy and common sense. Think of the most brittle and painful code you've ever worked with. It didn't get that way all at once. Person by person, edit by edit, deadline by deadline it slowly descended into a blackhole of entropy.

    A vicious cycle ensued: the more brittle that code became, the longer each change took and the more the developers complained there was no time clean it up. Do yourself a favor and clean as you go... you and your team will be the better for it.


  • #2 - Never clean up code that will not be tested.

    Cleaning up code that's not going to be tested is like playing Russian Roulette; if you clean up enough code eventually your luck will run out. That's why it's critical to only change code you know will be tested.

    If you're fixing a bug or adding a feature that code should already be covered by either unit tests or human testers (QA/QC), so you're golden. If you see other code that's in desperate need of a clean up but isn't covered by tests then either arrange for tests or leave it alone.

    Whats the worst that could happen? A really nasty subtle bug slips into production and isn't immediately caught. Depending on the application this may be a minor inconvenience or the end of the world. Manage your risks accordingly.


  • #3 - If you mix your refactoring with your maintenance its not refactoring.

    Refactoring by definition is changing structure without changing functionality. Making structural changes while making functional ones is a sure way to find yourself at a dead-end that requires you to roll back everything you've done (or worse yet end up with a brittle working mess that's near impossible to straighten out).

    Refactor. Test. Check-in. Repeat as necessary. Then make functional changes.

    Its best to refactor first for clarity. This makes the code easier to understand and gives you a solid place to roll back to. Once that's checked in refactor again to make it the specific pieces that need to be changed easier to work with. Often this means isolating the code the code that you will change in its own functions and even adding pseudo code to note the expected changes. Check in again.

    Make functionality changes, test and check in again. After your changes are complete you can refactor again if needed to clean up your own mess.


  • #4 - Incremental improvements are more stable than large sweeping ones, don’t try to fix everything all at once.

    Small changes are easy to understand, easy to validate and easy to undo if they cause problems. In systems of any complexity large changes are difficult to understand and are likely to have unintended side effects which will be difficult to identify and resolve. 


  • #5 - If you have taken the time to understand difficult piece of code then take a little more time to make it more clear.

    This may be renaming variables, functions or classes to match their purpose or more complicated refactorings or it may be as simple as adding comments to the code.


Following these tips consistently over time (especially if done as a team) can make your brown field a cleaner and a more pleasant place to be.

If you have any tips you'd like to share please leave a comment.

0 - What do you think?: