You Have an Architecture

The Symptoms

There we are standing in front of the whiteboard at 5:00 on Friday afternoon.  Myself, the development manager, and a couple gifted software engineers are staring at the multicolor boxes and lines scribbled on the board.  A feeling of defeat flows through the groups psyche.  Yet again, while trying to come up with a solution to the latest critical bug, we have all made the realization that the architecture of the system is severely broken.  Fixing this bug is going to take an inordinate amount of time.  A new concept will likely need to be introduced which means touching just about every piece of the system.  As we all shake our heads and shrug our shoulders in silence somebody says “Well at least now we know what the architecture is.  I’m going for a beer; anybody in?”

How can this be?  How is it that multiple years into a project costing millions of dollars the development team doesn’t know what the architecture is? I had jokingly heard the phrase “Every software has an architecture even if it is only defined in code”.  I assumed this must only be true on undisciplined teams, teams that grew too large or too fast, or teams that had deadlines that were too short.  As I started digging in a little I found this is a common problem.  I saw the quote rephrased “It’s fair to say that every software system has an architecture, but not every software system has a defined architecture.”  I have heard the concept named ad hoc architecture or agile architecture.  I gathered from my reading that many devs have to work with these types of designs.  Many don’t know any different because it is the norm at their current and past companies.  Others have come to fear the missing architecture because they know the thrashing it causes.

The Diagnosis

The signs of having an undocumented architecture are many. One of the first signs is these head scratching sessions that end in the inability to add a feature or fix a problem without some major refactoring. When fixing bugs is harder than pulling teeth, you might have an undocumented architecture.  Another sign is constant excuses from developers about why they are missing deadlines. It may go something like this “Well yeah I know I told you it was only going to take a few days but once I got in there I found….”.  When every estimate, even from senior developers, is more than 20% low, you might have an undocumented architecture.  If the symptoms are so bad for the experienced veterans imagine what it is like for the junior guys only coming into their first or second project.  If it is the opinion of the team that it takes nearly a year to bring new developers up to speed, you might have an undocumented architecture.

The longer a project goes with an undocumented architecture the more technical debt is accrued against the project.  Without a strong  big picture design developers are likely to fix problems and add features in a localized way.  Picture a large game of Jenga. Each player is only concerned about moving a single block on their turn and adding to the top of the tower.  As the tower becomes more and more unstable it is less likely that the player will get another turn and knock over the tower. So each player more and more carefully removes a block with no concern for the overall stability because it becomes the next persons problem. Software development on an ad hoc architecture follows a similar pattern. Every bug fix and feature is surgically added so as not to disrupt the overall design. Soon though the project is top heavy and there is not enough infrastructure to support the next piece. CRASH! The whole thing comes tumbling down on the poor unsuspecting developer who just wanted to fix one last bug before the end of the iteration. Time for a major refactor.

The Treatment

You might have an undocumented architecture, now what?  Well first off don’t panic and run off looking for another project because there is hope. Step one hire, find, appoint, or imprison one of those software architect types. This person doesn’t have to be a rock star architect.  They don’t even have to be experienced to start with. Just find a decent engineer, with the ability to wield a word processor as well as they do a compiler, who is a big picture thinker, and ask them if they want to give it a try.

Now that the project has an architect give the person time to document the architecture that exists. This is not a part time job. Two hours a week is not sufficient. I’m talking about real time, 70% – 100% of their time focused on architecture. Trust me, the entire team will be more productive which will more than pay for the loss of coding time. This process is called architecture reconstruction and there are documented techniques for doing it. Even if it is not done exactly right some documentation is surely better than none.

Once the architecture is documented it is time to start finding and plugging the holes.  That means paying back all the technical debt that has been accumulating behind the scenes as developers have been working hard to add visible value as fast as they can while not toppling the tower. Identify all this work that needs to be done, track it, and plan it just like any other work.  This is going to make stakeholders sad in the beginning because they will be getting less features. If they are patient though they will soon be rewarded with faster more stable feature development which is what they wanted all along.

Lastly don’t fall back into old habits. Continue to make time to document architecture. Continue to design up front what should be done and then go back and reconstruct what was actually done. Constantly patrol for technical debt and fight to pay it back as soon as possible.  Do this and you may never again have to suffer that five o’clock Friday despair that drives you to the bottom of pint.  Instead enjoy that pint because you just shipped the best release yet.