Start writing good code

An argument for breaking bad habits in code

I've started to keep track of the times where people don't give their best even when they know they could be. One general theme has stuck out and I want to put it to bed. I want it out of the excuse war chest.

The theme of excuses is "the existing code is bad, but I don't want to deviate to keep consistency/familiarity."

Note that people may disagree on what good or better code is in any given situation. This is not a piece about arguing for any solution. I'm talking about the scenario where an individual decides that the code is bad but embraces it anyway.


This theme can demonstrate itself in many forms:

  • Copying bad names. For example, a few methods are misnamed, misspelled, or are named cryptically and new methods follow suit.

  • Copying bad patterns. Feature A was built in this style so feature B is built in the same style. This is often using something like an object-oriented programming (OOP) code organization pattern or writing code within a framework.

  • Copying bad processes. Feature A was released or made available this way so feature B is rolled out the same way. Another: tests weren't written for X so tests aren't needed for Y.

  • Adding more code in existing bad code. An existing feature is complicated and takes quite a while to grok, so the additions only make it harder to grok.

  • Coupling new code to bad code. Feature B needs feature A but feature A is a real pain to work with, so the struggle is made to get it wired up directly.


The results of these decisions take the shape of:

  • Contributing to a greater debt than was there. The current debt has been recognized as you have (perhaps unintentionally) decided to add to it.

  • Constricting your work to the lowest common denominator. If everyone took the path of copying what was there, the best code could only be what was originally written. Future people tend to have a better idea of what the appropriate way to organize and design something is.

  • Encouraging further debt. Engineering culture is a mind virus. Rest assured that the natural track of an engineer is to copy and cargo-cult existing code. Bad code begets bad code. I would describe a good amount of my time at work as stamping out viruses before they can spread too far.


  • Rip the bandage and cut a new path. Let the old things be the only wrong things. Macro-consistency is overrated and limits better solutions. Strive for feature-internal consistency instead. The most important thing is to try to model any given problem the best you can and from there it can be composed into other systems. The macro consistency can be achieved at a higher layer.

  • Approach every problem from first principles. Don't make the mistake of assuming any previously solved problem is your problem and thus needs the same solution. Make sure every piece of a solution justifies itself in isolation such that things are kept simple.

  • Insulate your new code from the old code. Make the boundaries between the new code and old code as small and well-defined as possible. The new code should be as decoupled as it can be such that if the day finally comes to kill the bad code, it will be much easier. Other new code can also benefit from those minimal contracts instead of interfacing directly.

  • Most importantly, believe in yourself and push yourself to be surrounded by and creating excellence today! You can start writing good code whenever you want. Your time is valuable, don't spend it propagating messes.

Make better arguments for your decisions. Keeping a status quo when there is a better solution is not a good idea on its own.