Documenting Software Architectures: Views and Beyond (2nd Edition)

582 Pages·2010·6.43 MB·English

by  David Garlan

ptg
Software
Architecture
Document
Set of Relevant Information That
Views consists of consists of Applies to More
Than One View
(Section 10.2)
includes
is documented
one or consists of
using
more
Template for 1. Documentation
Information Beyond Roadmap
View Views 2. How a View Is
(Section 10.2) Documented
(see inside back
3. System Overview
cover)
is chosen 4. Mapping
to document Between Views
based on
View Template 5. Rationale
(Section 10.1)
6. Directory
Structures Designed (see inside back
into the Architecture cover)
ptg
is documented
using
is chosen
to document
based on
Meeting
Documentation
Stakeholders’ Needs
(Chapter 9)
consists of
View Packets
(Section 10.1.2)
may be
divided
into
1. Primary Presentation
2. Element Catalog
a. Elements and Their Properties (Chapters 1–5)
b. Relations and Their Properties (Chapters 1–5)
c. Element Interfaces (Chapter 7) Key
d. Element Behavior (Chapter 8)
A label B
3.Context Diagram (Section 6.3)
4.Variability Guide (Section 6.4)
5.Rationale (Section 6.5) Concept A has relationship “label” with Concept B.
when applied to a
View Style
system, yields a
(Prologue Section P.3) (Prologue Section P.4) chosen for
use by
architect to
achieve
Quality Attributes
may may may may combines
be be be be one or
more
Module Style Component-and- Allocation Style Hybrid Style
(Chapters 1 and 2) Connector Style (Chapter 5) (Section 6.6)
(Chapters 3 and 4)
such as such as such as
Decomposition Pipe-and-Filter Deployment
Style Style Style
(Section 2.1) (Section 4.2.1) (Section 5.2)
ptg
Uses Style Client-Server Install Style
(Section 2.2) Style (Section 5.3)
(Section 4.3.1)
Generalization Work
Style Peer-to-Peer Assignment
(Section 2.3) Style Style
(Section 5.4)
(Section 4.3.2)
Layered Style
(Section 2.4) Other Allocations
Service-Oriented
Styles
Architecture
(Section 5.5)
Aspects Style Style
(Section 2.5) (Section 4.3.3)
Publish-
Data Model
Subscribe Style
Style
(Section 4.4.1)
(Section 2.6)
Shared-Data
Style Key
(Section 4.5.1)
A label B
Multi-tier Style
(Section 4.6.2) Concept A has relationship “label” with Concept B.
Praise for the First Edition of Documenting Software Architectures
“For many years, box and line diagrams have decorated the text that describes system
implementations. These diagrams can be evocative, sometimes inspirational, occasionally
informative, but are rarely precise and never complete. Recent years have brought appreci-
ation for the importance of a deliberate structural design, or architecture, for a system. Now,
in Documenting Software Architectures, we have guidance for capturing that knowledge,
both to aid design and—perhaps more significantly—to inform subsequent maintainers,
who hold over half the total cost of a system’s software in their hands. Half of this cost goes
into figuring out how the system is organized and where to make the change. A documented
architecture is the essential roadmap for the system, leading the maintainer through the
implementation jungle.”
ptg
—Mary Shaw, Alan J. Perlis Professor of Computer Science, Carnegie Mellon University
Coauthor of Software Architecture: Perspectives on an Emerging Discipline
“Multiple software architecture views are essential because of the diverse set of stakeholders
(users, acquirers, developers, testers, maintainers, inter-operators, and others) needing to
understand and use the architecture from their viewpoint. Achieving consistency among
such views is one of the most challenging and difficult problems in the software architecture
field. This book is a tremendously valuable first step in defining analyzable software architec-
ture views and frameworks for integrating them.”
—Barry Boehm, TRW Professor of Software Engineering
Director, USC Center for Software Engineering
“There is probably no better set of authors to write this book. The material is readable. It uses
humor effectively. It is nicely introspective when appropriate, and yet in the end it is forthright
and decisive. The philosophical elements of the book are fascinating. The authors consider
concepts that few others even are aware of, present the issues related to those concepts,
and then resolve them! This is a tour de force on the subject of architectural documentation.”
—Robert Glass, Editor-in-Chief, Journal of Systems and Software
Editor/Publisher, The Software Practitioner
“We found this book highly valuable for our work with our business units and would recom-
mend it to anyone who wants to understand the needs for and improve their skills in describ-
ing software architectures for complex systems.”
—Steffen Thiel, Robert Bosch Corporation
“Since our projects involve numerous stakeholders, documenting the architecture from var-
ious views is of particular importance. For this task, this book provides pragmatic and well-
structured guidance and will be an important reference for industrial practice.”
—Martin Simons, Daimler Chrysler Research and Technology
“Software architecture is an abstract representation of the most essential design decisions.
It is expressed using concepts that are not directly visible in software implementation. How
to identify these decisions? How to represent them? How to find the concepts that make
complex software understandable? This excellent book is written by a group of expert archi-
tects sharing their experience and understanding of useful architectural concepts, essential
design decisions, and practical ways to represent architectural views of complex software.”
—Alexander Ran, Principal Scientist of Software Architecture, Nokia
“I particularly appreciate the major theme of the book: that a software architecture consists
of a variety of different structures, each defined by a set of elements and a relationship
among those elements. I further appreciate the authors pointing out why the diagrams that
seem so beloved by today’s software designers are often deceptive and of little value. (I fre-
quently say that in software engineering every diagram takes a thousand words to explain
it.) It was also refreshing to see an explanation of why ‘levels of abstraction,’ a favorite term
of many software designers, is an empty phrase. These are just a few of the elements that
made me impatient to see this book published.”
—David Weiss, Director of Software Technology Research, Avaya Laboratories
“The authors have written a solid book that discusses many of the most important issues
ptg
facing software designers. They point out many decisions that can be considered, dis-
cussed, and made before coding begins to provide guidance for the programmers. These
issues are far more important than most of the decisions that programmers focus on. Prop-
erly made and documented, the decisions discussed in this book will guide programmers
throughout the remainder of the software development process.”
—David Parnas, Director of the Software Engineering Programme, McMaster University
Documenting Software Architectures
Second Edition
ptg
Documenting Software Architectures
Views and Beyond
Second Edition
Paul Clements
ptg
Felix Bachmann
Len Bass
David Garlan
James Ivers
Reed Little
Paulo Merson
Robert Nord
Judith Stafford
Upper Saddle River, NJ • Boston • Indianapolis • San Francisco
New York • Toronto • Montreal • London • Munich • Paris • Madrid
Capetown • Sydney • Tokyo • Singapore • Mexico City
Many of the designations used by manufacturers and sellers to distinguish their products are claimed as trademarks. Where
those designations appear in this book, and Addison-Wesley was aware of a trademark claim, the designations have been
printed with initial capital letters or in all capitals.
CMM, CMMI, Capability Maturity Model, Capability Maturity Modeling, Carnegie Mellon, CERT, and CERT Coordination Cen-
ter are registered in the U.S. Patent and Trademark Office by Carnegie Mellon University.
ATAM; Architecture Tradeoff Analysis Method; CMM Integration; COTS Usage-Risk Evaluation; CURE; EPIC; Evolutionary
Process for Integrating COTS Based Systems; Framework for Software Product Line Practice; IDEAL; Interim Profile; OAR;
OCTAVE; Operationally Critical Threat, Asset, and Vulnerability Evaluation; Options Analysis for Reengineering; Personal Soft-
ware Process; PLTP; Product Line Technical Probe; PSP; SCAMPI; SCAMPI Lead Appraiser; SCAMPI Lead Assessor; SCE;
SEI; SEPG; Team Software Process; and TSP are service marks of Carnegie Mellon University.
IEEE Std 1471 is a trademark of the Institute of Electrical and Electronics Engineers, Inc.
Special permission to reproduce portions of the following is granted by the Software Engineering Institute:
• Robert L. Nord, Paul C. Clements, David Emery, and Rich Hilliard, “A Structured Approach for Reviewing Architecture Doc-
umentation” (CMU/SEI-2009-TN-030). Copyright © 2009 by Carnegie Mellon University.
• Felix Bachmann, Len Bass, Paul Clements, David Garlan, James Ivers, Reed Little, Robert Nord, and Judith Stafford, “Doc-
umenting Software Architecture: Documenting Behavior” (CMU/SEI-2002-TN-001). Copyright © 2002 by Carnegie Mellon
University.
• Felix Bachmann, Len Bass, Paul Clements, David Garlan, James Ivers, Reed Little, Robert Nord, and Judy Stafford, “Doc-
umenting Software Architectures: Organization of Documentation Package” (CMU/SEI-2001-TN-010). Copyright © 2001
by Carnegie Mellon University.
• Felix Bachmann, Len Bass, Jeromy Carriere, Paul Clements, David Garlan, James Ivers, Robert Nord, and Reed Little,
“Software Architecture Documentation in Practice: Documenting Architectural Layers” (CMU/SEI-2000-SR-004). Copy-
right © 2000 by Carnegie Mellon University.
• Felix Bachmann, Len Bass, Paul Clements, David Garlan, James Ivers, Robert Nord, Reed Little, and Judith Stafford, “Soft-
ware Architecture Documentation in Practice: Documenting Software Interfaces” (CMU/SEI-2002-TN-015). Copyright ©
2002 by Carnegie Mellon University.
The authors and publisher have taken care in the preparation of this book, but make no expressed or implied warranty of any
kind and assume no responsibility for errors or omissions. No liability is assumed for incidental or consequential damages in
connection with or arising out of the use of the information or programs contained herein.
ptg
The publisher offers excellent discounts on this book when ordered in quantity for bulk purchases or special sales, which may
include electronic versions and/or custom covers and content particular to your business, training goals, marketing focus,
and branding interests. For more information, please contact:
U.S. Corporate and Government Sales
[phone]
[e-mail]
For sales outside of the U.S., please contact:
International Sales
[e-mail]
Visit us on the Web: informit.com/aw
Library of Congress Cataloging-in-Publication Data
Documenting software architectures : views and beyond / Paul Clements
... [et al.]. — 2nd ed.
p. cm.
Includes bibliographical references and index.
ISBN 978-0-321-55268-6 (hardcover : alk. paper)
1. Computer architecture. 2. Software documentation. I. Clements,
Paul, 1955– II. Title.
QA76.9.A73D63 2010
005.1'5—dc22
2010024318
Copyright © 2011 Pearson Education, Inc.
All rights reserved. Printed in the United States of America. This publication is protected by copyright, and permission must
be obtained from the publisher prior to any prohibited reproduction, storage in a retrieval system, or transmission in any form
or by any means, electronic, mechanical, photocopying, recording, or likewise. For information regarding permissions, write to:
Pearson Education, Inc.
Rights and Contracts Department
501 Boylston Street, Suite 900
Boston, MA 02116
Fax: [phone]
ISBN-13: 978-0-321-55268-6
ISBN-10: 0-321-55268-7
Text printed in the United States on Recycled paper at Courier in Westford, Massachusetts.
First printing, October 2010
These pictures are meant to entertain you. There is
no significant meaning to the arrows between the boxes.
—A speaker at a recent software architecture conference, coming to a
complex but ultimately inadequate boxes-and-lines-everywhere
viewgraph of her system’s architecture and deciding that trying to
explain it in front of a crowd would not be a good idea
I’d like to start with a diagram. It’s a bunch of shapes
connected by lines. Now I will say some impressive words:
synchronized digital integrated dynamic e-commerce space.
Any questions?
—Dilbert, making a viewgraph presentation
ptg
At the end of the day, I want my artifacts to be enduring.
My goal is to create a prescriptive, semi-formal architectural
description that can be used as a basis for setting
department priorities, parallelizing development, [managing]
legacy migration, etc.
—A software architect for a major financial services firm
This page intentionally left blank
ptg