Working software over comprehensive documentation? Don’t toss the architecture!

On April 22, 1889 at 11:59 AM, nearly a hundred thousand people were lined up on horses and wagons on the border of two million acres of what is now Oklahoma. They were all gathered in hopes of acquiring free land, since the The United States government declared that these two million acres would be free to whomever could claim it at noon that day. You can imagine the chaos that ensued when the signal was fired. Sam Anderson describes the scene in his book, Boom Town.

“… People are shooting guns to speed up their horses and accidentally shooting each other. Horses are dying of exhaustion. It’s … just about the wildest scene you can imagine.”

For many, this was a one-way ticket out poverty. For others, it was a financial opportunity; but one thing was for sure, nobody was very concerned about how to properly build a city under these circumstances. They needed space for roads, schools, fire/police stations and government buildings. In the following days after the event, most of the new landowners agreed to sign over portions of their land to build infrastructure for the city.

There was however, a group of people called the “Sooners” who refused to sign over any of their land. A compromise was eventually worked out with the Sooners, which resulted in strange features in the city called “jogs”. These crooked streets were built to connect two separate city grids, as you can see in the image below.

Jogs

All of us have seen these jogs in our code base at one point or another. Most programmers just accept it as the way things are, but it doesn’t have to be! These jogs can be significantly reduced if not completely eliminated in your code if there is a proper software architecture in place.

But wait, we practice Agile, so we don’t do documentation. Haven’t you read the Agile Manifesto?

Working software over comprehensive documentation

If your read this principle carefully, it is not saying to not write any documentation at all. It is simply warning you against comprehensive documentation. Software architecture documents are something that you should not neglect on most projects, and here I will explain three reasons why architecture documents can save your project from a terrible disasters, even in Agile.

1. Increases the scalability of your system

This is likely the most significant benefit to writing architecture documentation. As a code base grows, it becomes more complex. Once it reaches a size that is bigger than a single person can practically understand, you are going to run into a lot of problems. By writing out documents on how the system works, multiple people can work together on how components should interact. With this shared understanding, there are going to be significantly less bugs and performance problems as you scale.

2. Reduces cost by cutting duplicate code and simplifying the code base

Programmers tend to over-complicate things, teams of programmers will over-complicate things repeatedly. If the team has a single document with well-defined components, the chance of building something twice will decrease significantly. Be sure that all of your components list how they interact with other components in the system!

3. Assists in requirements gathering, serving as the source of truth for the system

To understand my point here, you need to understand the difference between functional and non-functional requirements.

  • A functional requirement describes a specific thing that the software must do.
  • A non-functional requirement is an attribute of the software. A client might say that the software needs to be performant, but lurking behind that request is a non-functional requirement. What they really mean is that the system can support 1000 simultaneous users.

Let’s face it, most clients do not know exactly what they want. It is our job as a software team to understand exactly what they are looking for. Odds are, they understand what the functional requirements of the system are, but they need you to help them specify the non-functional requirements. If you do not capture these non-functional requirements early on, you risk needing to completely refactor your entire code base to be acceptable to the client.

Don’t Skip the Architecture

Ultimately, writing and maintaining software architecture documents is critical for most projects. Agile is very focused on doing exactly enough to get things done, so there is a chance that architecture documents are not needed for a system, but this should be very rare. If done correctly, architecture documentation can reduce cost, risk, complexity, and delivery time.

Sources: