by Paul Clements, Felix Bachmann, Len Bass, David Garlan, James Ivers, Reed Little, Robert Nord, Judith Stafford
Addison-Wesley, 2002
ISBN: 0-201-703726
Cover price: US$59.99
640 pages

Ten years ago, I was brought in to lead the architecture team of a new and rather ambitious command-and-control system. After a rocky beginning, the architectural design work started to proceed full speed, with the architects finally forging ahead, inventing, designing, trying, and resolving, in an almost euphoric state. We had many brainstorming sessions, filling whiteboards with design fragments and notebooks with scribblings; various prototypes validated--or invalidated--our reasoning.

As the development team grew in size, the architects had to explain the principles of the nascent architecture to a wider and wider audience, consisting not only of new developers but also of many parties external to the development group. Some were intrigued by this new (to them) concept of a software architecture. Some wanted to know how this architecture would impact planning, organization of the teams and the contractors, delivery of the system, and acquisition of some system parts. Some parties wanted to influence the design of this architecture. At a further remove from development, customers and prospects wanted a peek, too. So the architects had to spend hours and days describing the architecture in various forms and levels and tones to varied audiences, so that each audience could better understand it.

Becoming such a center of communication slowly stretched our capacity. On one hand, we were busy designing, and validating the architecture; on the other hand, at the same time we were communicating to a large audience what the architecture was, why it was the way it was, and why we did not choose some other solution. A few months into the project, overwhelmed, we began having a hard time even agreeing among ourselves about what it was we had actually decided.

This led me to the conclusion that "If it is not written down, it does not exist." This became sort of a leitmotiv within the architecture team for the following two years. As the ancient Chinese poet Lao-Tsu says in the Tao Te Ching,

Let your workings remain a mystery.
Just show people the results.
(Tablet #36)

The architecture could have been whatever we had talked about, argued, imagined, or even drafted on a board. But in the end, the architecture of this system was only what was described in one major artifact: the Software Architecture Document (SAD). Architectural elements and architectural decisions not captured in this document simply did not exist. This one rule--"If is not in the SAD, it does not exist" --provided incentive to evolve the document and keep it up to date, almost to the week. It also gave us an incentive not to include anything and everything, such as untried ideas, in the SAD, which became the project's definitive arbiter and a central element in the life of the project. It was our display window for showing off our stuff, our comfort when we were down, and our shield when attacked.

The key questions we faced at the time were: What should we document for our software architecture? How should we document it? What outline should we use? What notation? How much or how little information should we include? There were few exemplars of architectural descriptions for systems as ambitious as ours. Driven by necessity, we improvised. We made mistakes, and corrected them. We rapidly discovered that architecture was not flat, but rather multidimensional, with several intertwined facets. Some facets--or views--were of interest to only a few parties. We found that many readers would not even open a document that weighed more than a pound, and that we would have a hard time updating it anyhow. We realized that, unless we captured the reasons for our choices, we were doomed to reconstruct them again and again, every time a new stakeholder with a sharp mind came around. We picked a visual notation that was neither too vague and fuzzy nor too esoteric and convoluted, to avoid discouraging most parties.

Today, software architects have a great starting point for deciding how to document their software architecture: With this book, you will have what you need in your hands. The authors went through many experiences similar to mine and extracted the important lessons learned. They read many software architecture documents. They reviewed the academic literature, studied all the published books, checked the standards, and synthesized all of this wisdom into this handbook, which describes the essential things you need to know in order to define your own software architecture document. You will find guidance for defining the document's scope and organization, and on the techniques, tools, and notation to use (or not to use), as well as comparisons, advice, and rules of thumb. You'll also find templates to get you started, and continuing guidance for the times you get lost or feel despair along the way.

This book is of immense value. Description and communication about a software architecture is crucial to that architecture's many stakeholders. This handbook can help you with both and save you from months of trial and error, lots of undeserved hassle, and many costly mistakes that could potentially jeopardize your entire endeavor. It is an important reference for the shelf of any software architect. If you have read and understood the IEEE Standard 1471-2000: "Recommended Practice for Architectural Description of Software Intensive Systems," but still wonder how to actually implement that practice, you will find this book is a complete Users' Guide that explains not only the "4+1 views" from the Rational Unified Process, but other approaches as well.

-Philippe Kruchten

About the author

Philippe Kruchten is former director and general manager of the IBM Rational Software Process Business Unit, in charge of the Rational Unified Process (RUP). He worked with Rational for thirteen years, in various functions and places: France, Sweden, the US, and Vancouver, Canada.

Philippe's main interests right now, besides software architecture and design, are software engineering and the development process. He is campaigning, in Canada, for the concept of state-licensed professional software engineers.

Comments (Undergoing maintenance)

Back to top

Trademarks  |  My developerWorks terms and conditions

Table of contents

• About the author
• Comments

Next steps from IBM

Rational Application Developer features provide the comprehensive Integrated Development Environment (IDE) used to develop J2EE applications requiring Servlets and JavaServer Pages (JSPs).

---

• Try: Try the free Rational Application Developer, which helps developers quickly design, develop, test, analyze, and deploy high-quality Java, Javaserver pages, and J2EE applications.
• Article: Learn how you can deliver accurate, higher-quality J2EE apps with Rational Application Developer, open source JUnit and JUnitEE test frameworks.
• Tutorial: Build a Facebook application using PHP, the Spring framework, and J2EE.
• Buy: Rational Application Developer

My developerWorks community

Dig deeper into Rational on developerWorks

Try Rational System Architect

See how this fully integrated collection of models and documents can help you better align your IT systems and infrastructure to simplify business processes

Special offers