Build code like you would pack a garage.

At my current job I am frustrated at how the code is being built. In order to explain it I came up with this analogy about packing a garage:

Say you have a big pile of stuff that you need to store. You rent a garage and start to fill it, putting things on the floor and stacking other things on top where they fit best. Eventually you have filled the garage with all the stuff and you close the door. Everything just fits so there is no wasted space. Job done.

The other way to do it would be to rent slightly bigger garage and install some proper storage shelves. You'd also get some boxes and marker pens and go through all the stuff and sort it into the right boxes: CD's in one, winter clothes in another. You put similar things near each other - like all the suitcases could be one one shelf. After a while everything is in and you close the door. Job done.

So one method is faster and cheaper, and both achieve the same objective which is to get stuff into the garage. Obviously the 'stuff it in' method is better.

Truth be told the 'stuff it in' method is better for filling the garage, and if that is all you want to do then fine. However if you ever want to get to anything in the garage you will realise that it was a mistake.

You have several problems to deal with. Firstly you can't find anything because there is no order and you have forgotten where you put things. Related things are not stored together so finding the ski boots does not get you closer to the skis. Also once you find something you can't get it out with out disturbing everything else. Finally because everything is so packed in you can't see it all so you can't be sure that there isn't a box at the back getting crushed.

Needless to say this is not the case with a properly stacked garage. Everything is on a shelf so it is easy to get to. Related things are collected in well labeled boxes so they are easy to find. When you find the necessary box you can pull it out without worrying about anything else falling down.

Bringing this back to code you can probably see the parallels. The 'stuff' that needs to go in the garage are the features of your code. Poorly written code is not well organized. All the functional code was just packed in as and when it was needed so it is not possible to easily find anything. Related bits of code end up in different files. There is lots of 'action at a distance' and plenty of side effects. Fixing or changing one bit of code can cause another to fail, seemingly for no reason, and this failure way not be obvious for some time.

Another parallel is that a tidy garage stays tidy because anything out of place looks messy and wrong. However once there is a little mess more mess quickly builds up and you start to lose the benefits of a tidy garage.

Code goes downhill in the same way. Regardless of how hard you try to keep it tidy if there is someone on your team who litters then it starts to bring everything down. Soon you stop being a coder and start being a cleaner. Or you leave it too long and suddenly you realise that it is all a big mess, that the best way to fix it is to take everything out, sort through it and put it back in again. But if a messy garage is not seen as a problem then the cleanup will not last, and you are wasting your time.

If you find yourself in this position I hope this analogy helps you.