Documenting Software Architectures: Views and Beyond, 2nd edition

Foreword to the Second Edition xxiii

Foreword to the First Edition xxv

Preface xxix

Acknowledgments xxxiii

Reader’s Guide xxxv

Prologue: Software Architectures and Documentation 1

P.1: A Short Overview of Software Architecture 1

P.2: A Short Overview of Architecture Documentation 9

P.3: Architecture Views 22

P.4: Architecture Styles 25

P.5: Seven Rules for Sound Documentation 36

P.6: Summary Checklist 45

P.7: Discussion Questions 46

P.8: For Further Reading 47

Part I: A Collection of Software Architecture Styles 49

I.1: Three Categories of Styles 49

I.2: Style Guides: A Standard Organization for Explaining a Style 50

I.3: Choosing Which Element and Relation Properties to Document 52

I.4: Notations for Architecture Views 53

I.5: Examples 54

Chapter 1: Module Views 55

1.1: Overview 55

1.2: Elements, Relations, and Properties of Module Views 56

1.3: What Module Views Are For 59

1.4: Notations for Module Views 60

1.5: Relation to Other Views 63

1.6: Summary Checklist 63

1.7: Discussion Questions 64

1.8: For Further Reading 64

Chapter 2: A Tour of Some Module Styles 65

2.1: Decomposition Style 65

2.2: Uses Style 74

2.3: Generalization Style 82

2.4: Layered Style 87

2.5: Aspects Style 104

2.6: Data Model 109

2.7: Summary Checklist 120

2.8: Discussion Questions 120

2.9: For Further Reading 121

Chapter 3: Component-and-Connector Views 123

3.1: Overview 123

3.2: Elements, Relations, and Properties of C&C Views 126

3.3: What C&C Views Are For 136

3.4: Notations for C&C Views 139

3.5: Relation to Other Kinds of Views 148

3.6: Summary Checklist 150

3.7: Discussion Questions 151

3.8: For Further Reading 152

Chapter 4: A Tour of Some Component-and-Connector Styles 155

4.1: An Introduction to C&C Styles 155

4.2: Data Flow Styles 157

4.3: Call-Return Styles 161

4.4: Event-Based Styles 172

4.5: Repository Styles 178

4.6: Crosscutting Issues for C&C Styles 182

4.7: Summary Checklist 185

4.8: Discussion Questions 186

4.9: For Further Reading 187

Chapter 5: Allocation Views and a Tour of Some Allocation Styles 189

5.1: Overview 189

5.2: Deployment Style 191

5.3: Install Style 198

5.4: Work Assignment Style 202

5.5: Other Allocation Styles 206

5.6: Summary Checklist 213

5.7: Discussion Questions 213

5.8: For Further Reading 214

Part II: Beyond Structure: Completing the Documentation 215

Chapter 6: Beyond the Basics 217

6.1: Refinement 218

6.2: Descriptive Completeness 222

6.3: Documenting Context Diagrams 225

6.4: Documenting Variation Points 231

6.5: Documenting Architectural Decisions 239

6.6: Combining Views 250

6.7: Summary Checklist 258

6.8: Discussion Questions 259

6.9: For Further Reading 260

Chapter 7: Documenting Software Interfaces 261

7.1: Overview 261

7.2: Interface Documentation 265

7.3: A Standard Organization for Interface Documentation 271

7.4: Stakeholders of Interface Documentation 278

7.5: Conveying Syntactic Information 279

7.6: Conveying Semantic Information 280

7.7: Examples of Interface Documentation 281

7.8: Summary Checklist 285

7.9: Discussion Questions 286

7.10: For Further Reading 286

Chapter 8: Documenting Behavior 289

8.1: Beyond Structure 289

8.2: How to Document Behavior 290

8.3: Notations for Documenting Behavior 295

8.4: Where to Document Behavior 306

8.5: Why to Document Behavior 306

8.6: Summary Checklist 308

8.7: Discussion Questions 309

8.8: For Further Reading 311

Part III: Building the Architecture Documentation 313

Chapter 9: Choosing the Views 315

9.1: Stakeholders and Their Documentation Needs 316

9.2: A Method for Choosing the Views 326

9.3: Example 329

9.4: Summary Checklist 335

9.5: Discussion Questions 335

9.6: For Further Reading 335

Chapter 10: Building the Documentation Package 337

10.1: Documenting a View 337

10.2: Documentation Beyond Views 350

10.3: Documenting a Mapping to Requirements 357

10.4: Packaging the Architecture Documentation 362

10.5: Summary Checklist 372

10.6: For Further Reading 373

Chapter 11: Reviewing an Architecture Document 375

11.1: Steps of the Procedure 376

11.2: Sample Question Sets for Reviewing the Architecture Document 382

11.3: An Example of Constructing and Conducting a Review 393

11.4: Summary Checklist 395

11.5: Discussion Questions 396

11.6: For Further Reading 396

Epilogue: Using Views and Beyond with Other Approaches 399

E.1: ISO/IEC 42010, née ANSI/IEEE Std 1471-2000 400

E.2: Rational Unified Process/Kruchten 4+1 406

E.3: Using the Rozanski and Woods Viewpoint Set 408

E.4: Documenting Architecture in an Agile Development Project 414

E.5: U.S. Department of Defense Architecture Framework 419

E.6: Where Architecture Documentation Ends 428

E.7: A Final Word 429

E.8: For Further Reading 429

Appendix A: UML—Unified Modeling Language 431

A.1: Introduction 431

A.2: Documenting a Module View 433

A.3: Documenting a Component-and-Connector View 438

A.4: Documenting an Allocation View 443

A.5: Documenting Behavior 449

A.6: Documenting Interfaces 460

Appendix B: SysML—Systems Modeling Language 465

B.1: Architecture Documentation 466

B.2: Requirements 466

B.3: Documenting a Module View 468

B.4: Documenting a Component-and-Connector View 469

B.5: Documenting an Allocation View 470

B.6: Documenting Behavior 471

B.7: Documenting Interfaces 472

B.8: Summary 472

Appendix C: AADL—The SAE Architecture Analysis and Design Language 473

C.1: Introduction 473

C.2: Documenting a Module Style 475

C.3: Documenting a Component-and-Connector View 478

C.4: Documenting a Deployment View 481

C.5: Documenting Behavior 482

C.6: Documenting Interfaces 484

C.7: Summary 484

Acronyms 487

Glossary 491

References 497

About the Authors 509

About the Contributors 513

Index 517