Software Architecture Documentation in Practice: …

1 Software Architecture Documentation in Practice: Documenting Architectural Layers Felix Bachmann Len Bass Jeromy Carriere Paul Clements David Garlan James Ivers Robert Nord Reed Little March 2000. SPECIAL REPORT. CMU/SEI-2000-SR-004. Pittsburgh, PA 15213-3890. Software Architecture Documentation in Practice: Documenting Architectural Layers CMU/SEI-2000-SR-004. Felix Bachmann Len Bass Jeromy Carriere Paul Clements David Garlan James Ivers Robert Nord Reed Little March 2000. Architecture Tradeoff Analysis Initiative Unlimited distribution subject to the copyright. This report was prepared for the SEI Joint Program Office HQ ESC/AXS. 5 Eglin Street Hanscom AFB, MA 01731-2116. The ideas and findings in this report should not be construed as an official DoD position.

2 It is published in the interest of scientific and technical information exchange. FOR THE COMMANDER. Norton L. Compton, Lt Col., USAF. SEI Joint Program Office This work is sponsored by the Department of Defense. The Software Engineering Institute is a federally funded research and development center sponsored by the Department of Defense. Copyright 2000 by Carnegie Mellon University. Requests for permission to reproduce this document or to prepare derivative works of this document should be addressed to the SEI Licensing Agent. NO WARRANTY. THIS CARNEGIE MELLON UNIVERSITY AND Software ENGINEERING INSTITUTE. MATERIAL IS FURNISHED ON AN AS-IS BASIS. CARNEGIE MELLON UNIVERSITY MAKES. NO WARRANTIES OF ANY KIND, EITHER EXPRESSED OR IMPLIED, AS TO ANY MATTER.

3 INCLUDING, BUT NOT LIMITED TO, WARRANTY OF FITNESS FOR PURPOSE OR. MERCHANTABILITY, EXCLUSIVITY, OR RESULTS OBTAINED FROM USE OF THE. MATERIAL. CARNEGIE MELLON UNIVERSITY DOES NOT MAKE ANY WARRANTY OF ANY. KIND WITH RESPECT TO FREEDOM FROM PATENT, TRADEMARK, OR COPYRIGHT. INFRINGEMENT. This work was created in the performance of Federal Government Contract Number F19628-95-C-0003. with Carnegie Mellon University for the operation of the Software Engineering Institute, a federally funded research and development center. The Government of the United States has a royalty-free government- purpose license to use, duplicate, or disclose the work, in whole or in part and in any manner, and to have or permit others to do so, for government purposes pursuant to the copyright license under the clause at Use of any trademarks in this report is not intended in any way to infringe on the rights of the trademark holder.

4 For information about purchasing paper copies of SEI reports, please visit the publications portion of our Web site ( ). Table of Contents Abstract iii Preface to the Special Report v Preface to Software Architecture Documentation in Practice vii 1 Documenting Software Architectures 1. Rules for Sound Documentation 2. Views 6. Uses of Architecture Documentation 8. 2 The Layered View 11. Introduction 11. Elements/Relations/Properties of the Layered View 14. Semantics and Well-Formedness 16. What It's For and What It's Not For 17. Notations 18. Variations 20. Confusions 23. Related Concepts 25. Vocabulary 26. References 26. Sidebar: Upwardly Mobile Software 28. CMU/SEI-2000-SR-004 i ii CMU/SEI-2000-SR-004. Abstract This report represents the first milestone of a work in progress.

5 That work is a comprehensive handbook on how to produce high-quality Documentation for Software architectures. The handbook, tentatively entitled Software Architecture Documentation in Practice, will be pub- lished in mid- to late-2000 by Addison Wesley Longman as a book in the SEI series on soft- ware engineering. Aimed squarely at the practitioner, the handbook is intended to fill a gap in the literature: There is a complete lack of language-independent guidance about how to actu- ally capture an Architecture in written form so that it can fulfill its purpose as a communication vehicle providing a unified design vision to all of the varied stakeholders of a development project. The theme of the work is that documenting an Architecture entails documenting the set of rele- vant views of that Architecture , and then completing the picture with Documentation of infor- mation that transcends any single view.

6 The report lays out our approach and organization for the complete book, and provides full guidance for one of the most commonly used architec- tural views: the layer diagram. The audience for this book is the community of practicing architects, apprentice architects, and developers who are on the receiving end of architectural Documentation . CMU/SEI-2000-SR-004 iii iv CMU/SEI-2000-SR-004. Preface to the Special Report This special report represents the first milestone of a work in progress. That work is a compre- hensive handbook on how to produce high-quality Documentation for Software architectures. The handbook, tentatively entitled Software Architecture Documentation in Practice, will be published in mid- to late-2000 by Addison Wesley Longman as a book in the Software Engi- neering Institute (SEI) series on Software engineering.

7 Aimed squarely at the practitioner, the handbook is intended to fill a gap in the literature. There is no shortage of material on the importance of Architecture . There is less, but still plentiful, material on tools for crafting an Architecture well-suited to its purpose through the use of styles and patterns. And there is an over-abundance of material available on how to use particular design notations such as the Unified Modeling Language (UML) to specify designs. But there is a complete lack of lan- guage-independent guidance about how to actually capture an Architecture in written form so that it can fulfill its purpose as a communication vehicle providing a unified design vision to all of the varied stakeholders of a development project.

8 The theme of the work is that documenting an Architecture entails documenting the set of rele- vant views of that Architecture , and then completing the picture with Documentation of infor- mation that transcends any single view. What are the relevant views? It depends on your goals. Architecture Documentation can serve many purposes: a mission statement for implementors, a basis for analysis, the specification for automatic code generation, the starting point for sys- tem understanding and asset recovery, or the blueprint for project planning. Different views support different goals and uses, and so another tenet of Documentation is that what you write down depends on what you expect to do with the Architecture .

9 We envision a book in the 300-page range that conveys the following information: Uses of Software Architecture Documentation . How one documents depends on how one wishes to use the Documentation . We will lay out the possible end goals for Architecture Documentation , and provide Documentation strategies for each. Architectural views. We view documenting Software Architecture primarily as document- ing the relevant views, and then augmenting this information with relevant trans-views information. The heart of the book will be an introduction to the two dozen or so most rel- evant architectural views (grouped into major families) along with practical guidance about how to write them down. Examples will be included for each.

10 Documenting architectural styles. Styles and patterns have emerged as important tools in the architect's repertoire, and since many styles and patterns transcend single structures CMU/SEI-2000-SR-004 v (and often do so either unintentionally or ambiguously) we include a section on how to document architectural styles and patterns. Validating Documentation . Once Documentation has been created, it should be validated before being turned over to those stakeholders who depend on its quality. We will give a practical method for reviewing and validating architectural Documentation . We will organize the information so that the reader can quickly get the information needed to accomplish the task at hand. In particular, we will ask the reader to explicitly choose the usage planned for the Software Architecture Documentation .