Category: Software Architect

There is much debate in the software development community about the value of documentation, especially in regards to the design of the software itself. The disagreements generally cluster around the perceived value of doing a “big upfront design”, and the difficulties of maintaining design documentation synchronized with an ever-changing code base.

One type of documentation that ages well, doesn’t require much effort and almost always pays off is a record of the rationale behind decisions that are made regarding the software architecture. As explained in the axiom “Architectural Tradeoffs”, the definition of a software architecture is all about choosing the right tradeoffs between various quality attributes, cost, time, and other factors. It should be made clear to you, your managers, developers, and other software stakeholders why one solution was chosen over another and what tradeoffs this entailed (did you sacrifice horizontal scalability in the name of reducing hardware and licensing costs? Was security such a concern that it was acceptable to increase the overall response time in exchange for data encryption?).

The exact format of this documentation can vary according to what is appropriate for your project, from quick notes in a text document, wiki or blog, to using a more formal template to record all aspects of each architectural decision. Whatever the form and format, the documentation should answer the basic questions “What was that decision we made?”, and “Why did we make that decision?”. A secondary question that is often asked and should be documented is “What other solutions were considered, and why were they rejected?” (actually, the question usually asked is “Why can’t we do it MY way?”) The documentation should also be searchable so that you can easily find it whenever it’s needed.

This documentation may come in handy in a number of situations:

• As a means of communication to developers regarding important architectural principles that should be followed
• To get the team “on the same page”, or even head off a mutiny, when developers question the logic behind the architecture (or even to humbly accept criticism if it turns out a decision doesn’t hold up under scrutiny)
• To show to managers and stakeholders exactly why the software is being built the way it is (such as why an expensive piece of hardware or software is necessary)
• When handing off the project to a new architect (how many times have you inherited a piece of software and wondered exactly why the designers did it THAT way?)

However, the most important benefits that come from this practice are:

• It forces you to be explicit about your reasoning in order to verify that your foundations are solid (see the axiom “Challenge assumptions – especially your own”)
• It can be used as a starting point to re-evaluate a decision when the conditions that influenced the final decision have changed

The effort required to create this documentation is equivalent to jotting down a few notes whenever you have a meeting or discussion on the subject. Whatever the format you choose, this is one type of documentation that is worth the investment.

Wethern’s Law of Suspended Judgement states (in a rather tongue-in-cheek fashion) that “Assumption is the mother of all screw-ups.” A more popular take on this would be, “Don’t assume – it makes an ‘ass’ of ‘u’ and ‘me’.” But when you are dealing with assumptions that could cost thousands, if not millions of dollars, it’s not always a laughing matter.

Best practices in software architecture state that you should document the rationale behind each decision that is made, especially when that decision involves a trade-off (performance versus maintainability, cost versus time-to-market, and so on). In more formal approaches, it is common to record along with each decision the context of that decision, including the “factors” that contributed to the final judgement. Factors may be functional or non-functional requirements, but they also may just be “facts” (or factoids…) that the decision-makers found important (technology constraints, available skill sets, the political environment, etc.).

This practice is valuable because by way of listing these factors, it helps highlight assumptions that the architects may have that are affecting important decisions regarding the software that is being designed. Very often these assumptions are based on “historical reasons”, opinion, developer lore, FUDs, or even “something I heard in the hallway”:

• “Open source is not reliable”
• “Bitmap indexes are more trouble than they’re worth”
• “The customer would NEVER accept a page that takes 5 seconds to load”
• “The CIO would reject anything that isn’t sold by a major vendor”

It is important to make these assumptions visible and explicit for the sake of posterity and for future re-evaluation. However, it is even more critical to make sure that any assumptions that aren’t based on relevant empirical evidence (or a confirmation from the people involved, for political factors) be validated before a decision is finalized. What if customers can wait 5 seconds for critical reports if you provide a counter? In exactly what way is exactly which open source project unreliable? Have you tested the bitmap indexes on your data, using your application’s transactions and queries?

And don’t overlook the word “relevant.” Something that was true in an older version of your software may not be true today. The performance of bitmap indexes in one version of Oracle may not be the same as in another. An older version of a library may have had security holes that have already been fixed. Your old reliable software vendor may be on their last legs financially. The technology landscape changes every day, and so do people. Who knows? Maybe your CIO has become a closet fan of Linux.

Facts and assumptions are the pillars on which your software will be built. Whatever they are, make sure the foundations are solid.