[eBook - Software Engineering - PDF] Documenting Software Architecture - 01.11.2001 - Addison Wesley.pdf - Wzorce projektowe - wubudubu1

DRAFT COPY FOR REVIEW: DO NOT COPY WITHOUT PERMISSION

Documenting

Software Architectures

Paul Clements

Felix Bachmann

Len Bass

David Garlan

James Ivers

Reed Little

Robert Nord

Judy Stafford

1 November 2001 -- Second Review Edition (7 -3/8” x 9-1/4”)

Documenting Software Architectures

Clements, Bachmann, Bass, Garlan, Ivers, LIttle, Nord, Stafford

Note to Reviewers

This manuscript is fairly complete, but it is still a work in progress. In particular:

• We plan to include three running example applications throughout the book. The examples are a large

war-gaming simulation system, a satellite data collection and distribution system, and a small Java

application for telephony. Currently, the work is populated with smaller disjoint examples that illustrate

key points in place. The three running examples will for the most part complement, not replace, the

smaller examples as a way to lend continuity to the work.

• Several sections and sidebars have “tbd” marks, indicating areas that need completion.

• We will have all of the figures and illustrations re-drawn.

• We need to handle a number of details, such as nailing down internal cross-references, external

citations, discussion questions, glossaries, and advice checklists.

We also ask you to take a leap of visual faith. Our text includes many callouts, which are described in the Read-

er’s Guide.We want the book to have a distinctive visual style, and the callouts are adorned with visual icons

denoting their content. However, the callouts in this manuscript are poor, temporary attempts by amateurs.

These will be supplanted by a professional treatment given by people who know what they’re doing. We ask

you to use your imagination to see these callouts as they might appear in the final work. Also, in the final work,

the sidebars will really be off to the side, so that a reader can more easily skip them or read them at his or her

leisure.

As you read this manuscript, please keep the following questions in mind:

1. Clarity : After you read this book, would you be able to produce a software architecture documentation

package from it? If not, what sections lack the necessary clarity or prescriptive detail?

2. Right prescription : Is what we have prescribed within reason? Which parts of what we prescribe would

you jettison and why? What parts of a software architecture documentation package are essential, but

overlooked by this book?

3. Depth of coverage : How much of the material covers things you already knew and didn’t need to read

about again? What parts had too much coverage? Too little coverage? What parts had just the right depth

of coverage?

4. Sound organization : Is the book organized and laid out to help a first-time reader? Is the book organized

and laid out to help someone find specific information quickly? What would have helped make information

easier to find quickly?

5. Style : Was the book easy to read? Were the call-outs useful, enjoyable, distracting, annoying? What sty-

listic improvements could you suggest?

6. Favorites: What were your favorite parts of the book and why? What were you least favorite parts and

why?

7. Recommendation : Who will be interested in using this book? What books or techniques do you currently

use/recommend to document your architecture? Would you recommend this book to a software developer

who might have to produce or work from an architecture? Why or why not?

We are extremely grateful for your help. You can provide your comments to the author who sent you the manu-

script, or e-mail them to clements@sei.cmu.edu. Please provide your comments by Monday, November 12,

2001.

With very best regards and many thanks for your help,

Paul, Felix, Len, David, James, Reed, Rod, and Judy

Draft for review: Do not circulate without permission

“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

“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

Draft for review: Do not circulate without permission

Documenting Software Architectures

Clements, Bachmann, Bass, Garlan, Ivers, LIttle, Nord, Stafford

About the Cover

The cover shows a drawing of a bird’s wing by (???) sketched in (date). (A sentence or two about the drawing...)

Of all the metaphors for software architecture, an avian wing is one of the most compelling. It can be shown

emphasizing any of a number of structures -- feathers, skeletal, circulatory, musculature -- each of which must

be compatible with the others and work towards fulfilling a common purpose. The feathers are elements that at

a glance are replicated countless times across the wing, but upon closer inspection reveal a rich sub-structure

of their own, and small but systematic variations so that all feathers are almost alike but no two are identical.

The wing exhibits strong quality attributes: lightness in weight, aerodynamic sophistication, outstanding thermal

protection. Its reliability, cycling through millions of beats, is unparalleled. The wing can be said to have behav-

ior, and how it moves determines how the bird flies. In coarse terms, the wing extends, flaps, and retracts, but

in finer terms the bird commands movements almost too subtle to see to control pitch, roll, and yaw with ex-

quisite finesse. We try, and have tried for millennia, to comprehend the wing by examining its parts, from differ-

ent points of view. But the whole wing is much more than the sum of its elements and structures -- it is in the

whole that beauty and grace emerge. Mankind’s technology still cannot replicate its exquisite abilities. The com-

mon starling, a good but not a great flier, can slip through the air at 21 body lengths per second with merely

nominal effort. That’s about what the world’s fastest aircraft (at 2,000 miles per hour) is able to manage.

Figure 1: A European starling (Sturnus vulgaris) and a Lockheed SR-71, two black birds that travel at about the

same speed (measured appropriately) thanks to their superb respective architectures. [Photo on left from ht-

tp://www.stanford.edu/~petelat1/; may want to find one of a starling in flight. Photo on right from www.habu.org,

originally from Lockheed-Martin. Permission for both tbd .]

Structure, sub-structure, replication with variation, behavior, quality attributes, and emergent properties of the

entire system -- all of these are important aspects to capture when documenting a software architecture. We

haven’t learned how to document beauty and grace yet, but for that we substitute the documentation of rationale

-- what the designer had in mind. For software, we can do this. For the wing of a bird, we can only admire the

result.

Draft for review: Do not circulate without permission

Table of Contents

Note to Reviewers 2

About the Cover 4

Preface 5

Reader’s Guide

(reflects earlier organization -- re-write tbd) 7

Audience 7

Contents and Organization 7

Stylistic conventions 9

How to Read this Book; How to Use this Book 11

Commercial Tools and Notations 12

Acknowledgments (in progress) 14

Prologue: Software Architectures and Documentation 15

The Role of Architecture 15

Uses of architecture documentation 16

Seven Rules for Sound Documentation 24

Viewtypes and Styles 35

Viewtypes 35

Styles 36

Summary: Viewtypes, Styles, and Views 38

Glossary 41

Summary checklist 42

For Further Reading 42

Discussion questions 44

References (to be moved to central Bibliography in back) 45

Part I:

Software Architecture

Viewtypes and Styles 47

Chapter 1: The Module Viewtype 48

Draft for review: Do not circulate without permission

[eBook - Software Engineering - PDF] Documenting Software Architecture - 01.11.2001 - Addison Wesley.pdf

Plik z chomika:

Inne pliki z tego folderu:

Inne foldery tego chomika: