Chapter 3 Documentation of Software Architecture from a ...courses.ece.ubc.ca/417/public/Chap-3.pdf · Documentation of Software Architecture 2 ... Per Brinch Hansen, ... and Wolf

Unc

orre

cted

Pro

of

BookID 159171 ChapID 03 Proof# 1 - 30/06/09

Chapter 3 1

Documentation of Software Architecture 2

from a Knowledge Management Perspective – 3

Design Representation 4

Philippe Kruchten 5

Abstract In this chapter we survey how architects have represented architectural 6

knowledge and in particular architectural design. This has evolved over the last 7

3 decades, from very intuitive and informal, to very structured, abstract and for- 8

mal, from simple diagrams and metaphors, design notations, and specific languages. 9

As our understanding of architectural knowledge evolved, the importance of de- 10

sign rationale and the decision process became more and more prominent. There is 11

however a constant through this evolution: the systematic use of metaphors. 12

3.1 Introduction 13

When we speak about the documentation of software architecture, we are clearly 14

referring to the explicit aspect of architectural knowledge (see Sect. 1.2.2.1). “If it is 15

not written, it does not exist,” I used to tell members of an architecture team, prod- 16

ding them to document, i.e., make very explicit, what we had discussed at length in 17

a meeting, or the knowledge they had brought in from outside, their past experience 18

in general, and especially the decisions we had just made. 19

Architectural knowledge consists of architectural design – the blueprints of the 20

system under development – as well as the design decisions, assumptions, context, 21

and other factors that together determine why a particular final solution is the way 22

it is. Except for the architecture design part, most of the architectural knowledge 23

usually remains hidden and tacit – in the heads of the architects. An explicit rep- 24

resentation of architectural knowledge is helpful for building and evolving quality 25

systems [192]. 26

In this chapter, we will therefore focus on the lower right of the four quadrants 27

of knowledge described in Fig. 2.1, the externalized part of architectural knowl- 28

edge (as opposed to tacit knowledge): the application-specific explicit knowledge, 29

Philippe Kruchten (B)University of British Columbia, Vancouver, Canada, e-mail: [email protected]

M. Ali Babar et al. (eds.), Software Architecture Knowledge Management,DOI: 10.1007/978-3-642-02374-3 3, c© Springer-Verlag Berlin Heidelberg 2009

39

Unc

orre

cted

Pro

of


40 P. Kruchten

and, to a somewhat lesser extent, we will also focus on the lower left quadrant: the 30

application-generic explicit knowledge. 31

Architecture representation implies the use of models, architectural models. But 32

what is a model? M is a model of S if M can be used to answer questions about S, 33

where S is the system under consideration. 34

3.2 Evolution of Architectural Representation 35

The first reference to the phrase “software architecture” occurred in 1969 at a 36

conference on software engineering techniques organized by NATO [65]. Some 37

of our field’s most prestigious pioneers, including Tony Hoare, Edsger Dijkstra, 38

Alan Perlis, Per Brinch Hansen, Friedrich Bauer, and Niklaus Wirth, attended 39

this meeting. From then until the late 1980s, the word “architecture” was used 40

mostly in the sense of system architecture (meaning a computer system’s physi- 41

cal structure) or sometimes in the narrower sense of a given family of computers’ 42

instruction set. Key sources about a software system’s organization came from Fred 43

Brooks in 1975 [54], Butler Lampson in 1983 [198], David Parnas from 1972 to 44

1986 [244, 245, 246, 247], and John Mills whose 1985 article looked more into the 45

process and pragmatics of architecting [227]. The concept of software architecture 46

as a distinct discipline started to emerge in 1990 [297]. A 1991 article by Winston 47

W. Royce and Walker Royce (father and son) was the first to position software ar- 48

chitecture – in both title and perspective – between technology and process [269]. 49

Eberhardt Rechtin dedicated a few sections to software in his 1991 book Systems 50

Architecting: Creating and Building Complex Systems [263]. 51

3.2.1 Boxes and Arrows 52

In the 1970s and through most of 1980s, because the concept of software archi- 53

tecture was not very well delineated from that of software design or “high-level 54

design”, there was very little agreement on how to document software architecture. 55

Various mixes of “boxes and arrows” diagrams were used as models, far too often 56

with not much precise semantics behind the boxes, and even less behind the arrows. 57

Some of this remains today, and constitutes what I call the “PowerPoint” level of 58

software architecture documentation. It is still very valuable in bridging the gaps 59

between various groups of stakeholders (the various people the architect has to deal 60

with), such as marketing, sponsors, quality, process, approval, certification, etc. 61

3.2.2 Views 62

Still today, modern software architecture practices rely on the principles that Perry 63

and Wolf enounced in the late 1980s in their pretty and simple formula: Architec- 64

ture = {Elements, Form, Rationale} [250]. The elements are the main constituents 65

Unc

orre

cted

Pro

of


3 Documentation of Software Architecture 41

of any architectural description in terms of components and connectors, while the 66

nonfunctional properties guide the final shape or form of the architecture. Different 67

shapes with the same or similar functionality are possible, as they constitute valid 68

design choices by which software architects make their design decisions. These de- 69

cisions are precisely the soul of architectures, but they are often neglected during the 70

architecting activity as they usually reside in the architect’s mind in the form of tacit 71

knowledge that is seldom captured and documented in a usable form. Software ar- 72

chitecture started to take shape as an artifact of the design process that “encompasses 73

significant decisions about: 74

1. The organization of a software system 75

2. The selection of the structural elements and their interfaces by which a system 76

is composed with its behavior as specified by the collaboration among those 77

elements 78

3. The composition of these elements into progressively larger subsystems” (from 79

RUP [189, 152]) 80

For years, the generalized practice and research efforts have focused solely on the ar- 81

chitectural representation itself. These practices have long been exclusively aimed at 82

representing and documenting the system’s architecture from different perspectives 83

called architectural views. These views, which represent the interests of different 84

stakeholders, are offered as a set of harmonized descriptions in a coherent and 85

logical manner and also used to communicate the architecture. 86

3.2.3 The Architecting Process 87

The period between 1996 and 2006 brought complementary techniques in the form 88

of architectural methods, many of them derived from well established industry 89

practices. Methods like RUP (at Rational, then IBM) [189, 152], BAPO/CAFR (at 90

Philips) [237], S4V (at Siemens) [147, 300], ASC (at Nokia), ATAM, SAAM and 91

ADD (at the SEI) [175], among others, are now mature design and evaluation prac- 92

tices to analyze, synthesize, and valuate modern software architectures. In some 93

cases, the methods are backed by architectural description languages, assessment 94

methods, and stakeholder-focused, decision-making procedures. 95

Since many of the design methods were developed independently [146], they ex- 96

hibit certain similarities and differences motivated by the different nature, purpose, 97

application domain, or the size of the organization for which they were developed. 98

In essence, they cover essential phases of the architecting activity but are performed 99

in different ways. Common to some of these methods is the use of design decisions 100

that are evaluated during the construction of the architecture. These decisions are 101

elicited by groups of stakeholders, under the guide of architects, but the ultimate de- 102

cision makers are (a small group – often a single person) architects. Unfortunately, 103

design decisions and their rationale were still not considered as first-class entities 104

because they lack an explicit representation. As a result, software architects cannot 105

revisit or communicate the decisions made, which in most cases vaporize forever. 106

Unc

orre

cted

Pro

of


42 P. Kruchten

3.2.4 Architectural Design Decisions 107

Rationale was present in the 1992 formula of Perry and Wolf, but in reality, it was 108

rarely captured explicitly in a form that would allow it to be revisited. This remains 109

a prevalent issue. 110

Rus and Lindvall wrote in 2002 that “the major problem with intellectual capital 111

is that it has legs and walks home every day” [272]. Current software organizations 112

suffer the loss of this intellectual capital when experts leave. The same happens 113

in software architecture when the reasoning required for understating a particu- 114

lar system is unavailable and has not been explicitly documented. In 2004, Jan 115

Bosch stated that “we do not view a software architecture as a set of components 116

and connectors, but rather as the composition of a set of architectural design deci- 117

sions” [48, 161]. The lack of first-class representation of design rationale in current 118

architecture view models brought the need to include decisions as first-class citizens 119

that should be embodied within the traditional architecture documentation. 120

There are several benefits of using design rationales in architecture as a mean to 121

explain why a particular design choice is made or to know which design alterna- 122

tives have been evaluated before the right or the optimal design choices are made. 123

Benefits can be achieved in the medium and long term because documenting design 124

rationale prevents the need for architecture recovery processes, which are mostly 125

used to retrieve the decisions when design, documentation, or even the creators of 126

the architecture are no longer available. In other cases, the natural evolution of a soft- 127

ware system forces previous design decisions to be replaced by new ones. Hence, 128

maintaining and managing this architectural knowledge requires a continuous atten- 129

tion to keep the changes in the code and the design aligned with the decisions, and 130

to use these to bridge the software architecture gap. 131

3.2.5 Architectural Knowledge = Architectural 132

Design + Architectural Design Decisions 133

It is in this new context that Perry and Wolf’s old ideas [250] become relevant for 134

upgrading the concept of software architecture by explicitly adding the design deci- 135

sions that motivate the creation of software designs. Together with design patterns, 136

reference architecture, frameworks, etc., design decisions are a subset of the overall 137

architectural knowledge (AK) that is produced during the development of architec- 138

ture. Most of the tacit knowledge that remains hidden in the mind of the architects 139

should be made explicit and transferable into a useful form for later use, easing the 140

execution of distributed and collective decision-making processes. 141

The formula, Architectural Knowledge = Architectural Design + Architectural 142

Design Decisions, recently proposed by Kruchten, Lago and van Vliet [192], mod- 143

ernizes Perry and Wolf’s [250] idea and considers design decisions as part of the 144

architecture. We’ll use this formula: AK = AD + ADD, to structure the rest of this 145

chapter. 146

Unc

orre

cted

Pro

of



3.3 Architectural Design 147

For many years, architectural knowledge was represented in very ad hoc fashion: 148

boxes and arrows of unspecified or fuzzy semantic value; the PowerPoint level 149

of architectural description. The challenge was to describe in a truly multidimen- 150

sional reality in a 2-dimensional space. Because the model, M, was poor, the set 151

of questions that could be answered regarding the system it represented remained 152

limited. 153

3.3.1 Viewpoints and Views 154

In the early 1990s, several groups around the world realized that the architecture 155

of a large and complex software-intensive system was made of multiple entangled 156

structures, and that the poor attempts of representing architecture using a single type 157

of flat blueprint was inherently doomed to fail. Different parties (or stakeholders) 158

are concerned by different aspects of an architecture. Each of these aspects is a 159

viewpoint, and can be addressed by a certain kind of architecture representation, 160

with a notation and language of its own. The views, however, do not correspond to a 161

decomposition of the architecture in parts, but are different projections, abstractions 162

or simplifications of a more complex reality. 163

Figure 3.1 is an example of a set of five views (from [152] and [188]). Very 164

similar sets of views appeared at Siemens [300] and elsewhere. 165

This concept of multiple views is not new, and Paul Clements traced it to a 166

1994 paper by David Parnas: “On a buzzword: hierarchical structure”[245]. An ar- 167

chitectural view is a partial representation of a system, from the perspective of a 168

Logical ViewImplementation

View

ProcessView

DeploymentView

Use CaseView

ProgrammersSoftware management

System IntegratorsPerformanceScalabilityThroughput

End-userFunctionality

System EngineeringSystemtopology

Delivery, installationCommunication

Analysts, TestersBehavior

Fig. 3.1 RUP’s 4 + 1 views [152, 188]

Unc

orre

cted

Pro

of


44 P. Kruchten

well-defined set of architectural concerns. A viewpoint is a set of conventions for 169

the construction, interpretation, and use of a given architectural view. In a way, the 170

viewpoint is to a view what the legend is to a map [158]. Of great importance are 171

the view correspondences, that is, the relationships that exist between the elements 172

in one view and the elements in another view. 173

Much has been written on the concept of views for architectural description, in 174

particular by a group at the SEI led by Paul Clements [71] in their 2003 book Docu- 175

menting software architecture: views and beyond and by Rozanski and Woods [270] 176

who introduced the refinement of perspective. The IEEE standard 1471–2000 [155] 177

provides a guide for describing the architecture of complex, software-intensive sys- 178

tems in terms of views and viewpoints, but it does not offer a detailed description of 179

the rationale that guides the architecting process (see below). 180

3.3.2 Architecture Description Languages 181

Over the last 20 years computer scientists in academia around the world have tried 182

to create architecture description languages (ADLs) to capture, represent, and rea- 183

son about essential elements of the conceptual architecture of a software-intensive 184

system. This follows the long tradition of programming languages: no computer sci- 185

entist would be “complete” who has not created his or her own language, and the 186

compiler that goes with it. 187

What ADLs have in common is that they are able to denote essential elements 188

of an architecture – components, package, as well as the relationship between these 189

components: connectors, interfaces, and to a certain extent some of the character- 190

istics and behaviour of these components and connectors – so that some form of 191

analysis, verification, and reasoning can occur, to derive or assess completeness, 192

consistency, ambiguity, performance, and other qualities. ADLs often offer both a 193

textual and a graphical notation, the intention being to have them readable by both 194

humans and machines. 195

ADLs have evolved from Rapide at Stanford, to ACME (CMU), Wright (CMU), 196

C2 (UCI), Darwin (Imperial College), to name only a few. Koala – developed by 197

Philips and based on Darwin – is the only one that has had some industry pene- 198

tration, and is used primarily to configure product-line instances in the consumer 199

electronics domain. Also AADL was developed by the SAE based on MetaH for the 200

automotive industry. 201

Finally, there has been some heated debate on the question of whether or not the 202

unified modeling language (UML) is an ADL. While not limited to architecture, 203

UML 2.0 certainly has all the elements to describe architecture. It is the notation 204

used to represent the 4 + 1 views above [152]. 205

As an ADL is a notation to express an architectural model, encompassing the 206

key design decisions that bind the system, it should be an important tool for the 207

capture and representation of architectural knowledge. Unfortunately, so far, except 208

for UML, ADLs’ use has been very limited and mostly confined to academic labs. 209

Unc

orre

cted

Pro

of



3.3.3 Application-Generic Knowledge: Patterns, Standards, 210

Frameworks 211

When moving from application-specific to application-generic knowledge, across 212

a domain or a technology or simply a community of architects, some application- 213

generic architectural knowledge can be developed and captured, using pretty much 214

the same tools and techniques we’ve seen above in Sect. 3.3.1 and 3.3.2. 215

Patterns and Frameworks 216

Tagging behind the work of the famous “Gang of Four”, Buschmann and his gang 217

of five captured architectural patterns [64] followed by a few others: SEI [74]. 218

These patterns are technology neutral. But others can be technology and/or domain 219

specific, such as the architectural patterns developed in Microsoft’s practice and 220

patterns group’s handbook [225]. More ambitious, an architectural framework is a 221

set of common practices for architectural description established within a specific 222

domain or stakeholder community; it identifies generic concerns, and some prede- 223

fined viewpoints which frame these concerns. Examples of frameworks are TOGAF 224

(The Open Group Architectural Framework), MoDAF, the Zachman Framework, 225

RM ODP and ISO 19439 (FDIS). 226

Standards 227

IEEE Std 1471 [155] was the first formal standard for architectural description, in 228

active use since 2000. In 2007, IEEE 1471 became an international standard. Now 229

ISO and IEEE are jointly revising the standard as ISO/IEC 42010, Systems and 230

Software Engineering – Architecture Description [158]. 231

There are new knowledge mechanisms in ISO/IEC 42010. In a sense, every stan- 232

dard is knowledge-based, embodying a community consensus by creating a filter on 233

the world through its definitions, and establishing rules on what to do when those 234

definitions apply. An important element of IEEE 1471:2000 was the explicit con- 235

ceptual model (or ontology) upon which the standard was built. That model has 236

been useful in codifying architectural practice, in education and in advancing the 237

state of the practice. The most obvious knowledge mechanisms in ISO/IEC 42010 238

are those reflecting resources readily reusable by architects from one project to 239

another: architecture-related concerns, stakeholder identification, and architectural 240

viewpoints. 241

In the ongoing revision (working draft 3, Nov 8, 2008), ISO/IEC 42010 [158] is 242

considering several new mechanisms: 243

• Codifying architectural frameworks: for large-scale reuse and knowledge sharing 244

• View correspondences: for linking between views 245

• Architectural models and model types: for finer-grain reuse 246

• Enhanced architecture rationale and decision capture 247

where IEEE 1471 codified a terminology base and best practices applicable to 248

individual architecture descriptions, ISO/IEC 42010 introduces a further level of 249

conformance in defining the notion of an architecture framework, which we define 250

here as a set of best practices for a particular community or domain, characterized 251

Unc

orre

cted

Pro

of


46 P. Kruchten

by a set of concerns, stakeholders, viewpoints, and the correspondences between 252

those viewpoints. 253

From a knowledge perspective, the hope is that many of the practices currently 254

called architecture frameworks in the community can now be defined in a uni- 255

form way, thereby raising the level of understandability and interoperability – some 256

might say “reusability” – among architects working within different paradigms. 257

One mechanism added to support architecture frameworks is view correspondence 258

rules, a notion that was not ready for standardization in 2000 (R. Hilliard, personal 259

communication). 260

Methods 261

Finally, methods pertaining to software architecture do also capture some architec- 262

tural knowledge. This is the case for the Siemens method [147], IMB’s RUP [152], 263

the many SEI methods: ADD, ATAM, QAW [177, 34] or the Software Architecture 264

Review and Assessment handbook [236], for example. 265

3.4 Architectural Design Decisions 266

3.4.1 What Is an Architectural Design Decision? 267

In his 2003 paper, Jan Bosch [48] stressed the importance of design decisions as 268

“a first class citizen”, but did not describe in detail what they consist of. Tyree and 269

Ackerman describe the structure of an architectural design decision (see Table 1.1 in 270

Chap. 1) [325]. Kruchten in [190], then with Lago and van Vliet in [192], introduce 271

a more detailed template for documenting design decisions, particularly stressing 272

relationships between design decisions and between design decisions and other ar- 273

tifacts. Tang [314], Duenas and Capilla [66, 103] have variations, and the SHARK 274

workshop in 2006 attempted to reconcile all these views. 275

Here is an example of attributes of an architectural design decision, from [190] 276

and [192]: 277

• Epitome (or the Decision itself). This is a short textual statement of the design 278

decision, a few words or a one liner. This text serves to summarize the decisions, 279

to list them, to label them in diagrams, etc. 280

• Rationale. This is a textual explanation of the “why” of the decision, its justi- 281

fication. Care should be taken not to simply paraphrase or repeat information 282

captured in other attributes, but to add value. If the rationale is expressed in a 283

complete external document, for example, a tradeoff analysis, then the rationale 284

points to this document. 285

• Scope. Some decisions may have limited scope, in time, in the organizations, or in 286

the design and implementation (see the overrides relationship below). By default, 287

(if not documented) the decision is universal. Scope might delimit the part of the 288

system, a life cycle time frame, or a part of the organization to which the decision 289

applies. 290

Unc

orre

cted

Pro

of



Idea 0 Tentative 2 Decided 3 Approved 4

Rejected 1 Challenged 2

Obsolete 0

Fig. 3.2 Possible state machine for a decision, from [190]

• State. Like problem reports or code, design decisions evolve in a manner that may 291

be described by a state machine (see Fig. 3.2): 292

– Idea. Just an idea, captured so it is not lost, when brainstorming, looking at 293

other systems etc.; it cannot constrain other decisions other than ideas. 294

– Tentative. Allows running “what if” scenarios, when playing with ideas. 295

– Decided. Current position of the architect or architecture team; must be con- 296

sistent with other related decisions. 297

– Approved. Approved by a review, or a board (for low-ceremony organizations, 298

not significantly different than decided). 299

– Challenged. A previously approved or decided decision that is now in jeopardy; 300

it may go back to approved without ceremony, but can also be demoted to 301

tentative or rejected status. 302

– Rejected. A decision that does not hold in the current system; but we keep them 303

around as part of the system rationale (see subsumes below). 304

– Obsolesced. Similar to rejected, but the decision was not explicitly rejected 305

(in favour of another one, for example), but simply became “moot,” irrelevant, 306

e.g., as a result of some higher-level restructuring. 307

• Author, Time-stamp, History. The person who made the decision and when. 308

Ideally we collect the history of changes to a design decision. State changes 309

are important, but so are changes in formulation and scope, especially with 310

incremental architectural reviews. 311

• Categories. A design decision may belong to one or more categories. The list of 312

categories is open ended. Categories are useful for queries and for creating and 313

exploring sets of design decisions that are associated with specific concerns or 314

quality attributes. 315

• Cost. Some design decisions have an associated cost, so it is useful to reason 316

about alternatives. 317

Unc

orre

cted

Pro

of


48 P. Kruchten

• Risk. Traditionally documented by exposure – a combination of impact and like- 318

lihood factors – this is the risk associated with taking a particular decision (see 319

IEEE Std 1540-2001, for example). It is often related to the uncertainty in the 320

problem domain, or to the novelty of the solution domain, or to unknowns in 321

the process and organization. If the project is using a risk management tool, this 322

should simply link to the appropriate risk in that tool. 323

• Related decisions. Decision A “is related to” decision B in any of the following 324

ways: 325

– Constrains: “must use J2EE” constrains “use JBoss”. 326

– Forbids (or excludes): “sin single point of failure” forbids “use a central 327

server”. 328

– Enables: “use Java” enables “use J2EE”. 329

– Subsumes: “all subsystems are coded in Java” subsumes “subsystem XYZ is 330

coded in Java”. 331

– Conflicts with: “must use dotNet” conflicts with “must use J2EE”. 332

– Overrides: “the Comm subsystem will be coded in C++” overrides “the whole 333

system is developed in Java”. 334

– Comprises (is made of, decomposes into): “design will use UNAS as middle- 335

ware” decomposes into “rule: cannot use Ada tasking” and “message passing 336

must use UNAS messaging services” and “error logging must use UNAS error 337

logging services” and, etc. 338

– Is Bound to (strong): A constrains B and B constrains A. 339

– Is an Alternative to: A and B address the same issue, but propose different 340

choices. 341

– Is Related to (weak): There is a relation of some sort between the two de- 342

sign decisions, but it is not of any kind listed above and is kept mostly for 343

documentation and illustration reasons. 344

See Fig. 3.3 for an example. 345

• Relationship with External Artifacts. Includes “traces from,” “traces to,” and 346

“does not comply with.” Design decisions trace to technical artifacts upstream: 347

Fig. 3.3 Example of relationship between design decisions, from [203]

Unc

orre

cted

Pro

of



requirements and defects, and artifacts downstream: design and implementation 348

elements. They also trace to management artifacts, such as risks and plans. 349

These relationships are almost as important as the decisions themselves. It is through 350

these relationships that decisions can be put to practical use: understanding part of 351

the rationale – the reason for certain decisions, for the choices made from among 352

several alternatives, for the incompatibilities between choices – impacts the analysis 353

of “what is affected if we were to change X, or Z?” 354

3.4.2 A Taxonomy of Architectural Design Decisions 355

Architectural design decisions do not all play the same role in the architecting pro- 356

cess. Some are tightly coupled to the design itself, and can be traced directly to some 357

element (e.g., a class, a process, a package or subsystem, an interface) in the system 358

under development; other decisions are general properties or constraints that we im- 359

pose to the system, that sets of elements must satisfy, and, finally, some are linked 360

to the general political, sociological, and cultural environments of the development 361

or deployment. 362

3.4.2.1 Existence Decisions (“ontocrises”) 363

An existence decision states that some element/artifact will positively show up, i.e., 364

will exist in the system’s design or implementation. 365

There are structural decisions and behavioral decisions. Structural decisions lead 366

to the creation of subsystems, layers, partitions, and components in some view of 367

the architecture. Behavioral decisions are more related to how the elements inter- 368

act together to provide functionality or to satisfy some nonfunctional requirement 369

(quality attribute) or connector. Examples: 370

Dextrous Robot (DR) shall have a Laser Camera System. 371

DR shall use the Electromagnetic (EM) communication system to communicate with Ground- 372Control. 373

In themselves, existence decisions are not that important to capture since they are 374

the most visible element in the system’s design or implementation, and the rationale 375

can be easily captured in the documentation of the corresponding artifact or element. 376

But we must capture them to be able to relate them to other, more subtle decisions, 377

in particular to alternatives (see Fig. 2.1). 378

Unc

orre

cted

Pro

of


50 P. Kruchten

3.4.2.2 Bans or Nonexistence Decisions (“Anticrises”) 379

This is the opposite of an existence decision, stating that some element will not 380

appear in the design or implementation. In a way, they are a subclass of existential 381

decisions. 382

It is important to document bans precisely because such decisions are lacking 383

any “hooks” in traditional architecture documentation. They are not traceable to any 384

existing artifact. Ban decisions are often made as possible alternatives are gradually 385

eliminated. 386

3.4.2.3 Property Decisions (“Diacrises”) 387

A property decision states an enduring, overarching trait or quality of the system. 388

Property decisions can be design rules or guidelines (when expressed positively) 389

or design constraints (when expressed negatively), of a trait that the system will 390

not exhibit. Properties are harder to trace to specific elements of the design or 391

implementation because they are often cross-cutting concerns, or they affect too 392

many elements. Although they may be documented in some methodologies or pro- 393

cess in design guidelines (see RUP, for example), in many cases they are implicit 394

and rapidly forgotten, and further design decisions are made that are not traced to 395

properties. Examples: 396

DR motion should be accurate to within +1 degree and +1 inch. 397

DR shall withstand all loads due to launch. 398

3.4.2.4 Executive Decisions (“Pericrises”) 399

These are the decisions that do not relate directly to the design elements or their 400

qualities, but are driven more by the business environment (financial), and affect 401

the development process (methodological), the people (education and training), the 402

organization, and, to a large extent, the choices of technologies and tools. Executive 403

decisions usually frame or constrain existence and property decisions. Examples: 404

• Process decisions: 405

All changes in subsystem exported interfaces (APIs) must be approved by the CCB 406

(Change Control Board) and the architecture team. 407

• Technology decisions: 408

The system is developed using J2EE. 409

The system is developed in Java. 410

• Tool decisions: 411

The system is developed using the System Architect Workbench. 412

Software/system architecture encompasses far more than just views and quality at- 413

tributes a la IEEE std 1471-2000 [155]. There are all the political, personal, cultural, 414

Unc

orre

cted

Pro

of



financial, and technological aspects that impose huge constraints, and all the associ- 415

ated decisions are often never captured or they only appear in documents not usually 416

associated with software architecture. 417

3.4.3 Visualization of Set of Design Decisions 418

There are two delicate issues with sets of architectural decisions: 419

• How to capture them (and how much)? 420

• How to visualize them? 421

Capture is a process or method issue and will be covered in a subsequent chap- 422

ter. How many decisions and how much information must be captured are hard 423

questions that relate to the other, more fundamental, question: what is the scope of 424

architecture? In Chap. 1 we stressed that architecture is a global, high-level, early 425

process, aimed at making hard, long-lived, and hard-to-change choices. Still per- 426

tinent to the issue of knowledge representation is: how do we represent sets of 427

interrelated decisions? 428

Assuming that we have captured a set of architectural design decisions, along 429

the lines of Sect. 3.4.1 above, how would we want to visualize them? The tabular 430

approach is not very exciting (see Fig. 3.4). 431

We can also represent architectural design decisions as graphs, stressing the re- 432

lationships we have described in Sect. 3.4.1, but these graphs rapidly become very 433

complex (see Fig. 3.5), and we need to introduce mechanisms for: 434

• Eliding (eliminating certain relationships), or zooming in and out (getting more 435

or less information about decisions) (see Fig. 3.6). 436

Fig. 3.4 The tabular representation (from [202])

Unc

orre

cted

Pro

of


52 P. Kruchten

Fig. 3.5 Decision graph from Spar Aerospace Dexterous Robot (fragment) [190]

Fig. 3.6 Zooming on a graph (from [203])

• Filtering (limiting the number of decisions in a view based on a set of criteria) or 437

clustering (grouping decisions according to some criteria) (see Fig. 3.7). 438

• Focusing (using some decision as an anchor, or a center for displaying other 439

decisions). 440

• Sequencing (laying out on a time line). 441

In particular, the focus on one particular decision supports the concept of impact 442

analysis: show me all the decisions that are affected by this one decision (see 443

Fig. 3.8) [190, 193, 201, 203, 204]. 444

A sequence of design decisions over a period of time supports the concept of 445

incremental architectural review: what are the decisions that have been made or 446

changed since the last review? 447

Unc

orre

cted

Pro

of



Fig. 3.7 Clustering decisions by classes (from [192])

3.4.4 A “Decisions View” of Architecture 448

If views and viewpoints are a good practice to document the design, and if a set of 449

design decisions offers a good complement in capturing (externalizing) additional 450

architectural knowledge, then there might be a way to combine the two approaches 451

for more cohesiveness and homogeneity. This is what Duenas and Capilla [103] 452

have done in proposing a decision view of software architecture in which decisions 453

are entangled with design for each architectural view. 454

This new perspective extends the traditional views that are described in the IEEE 455

Std. 1471 [155] by superimposing the design rationale that underlies and motivates 456

the selection of concrete design options. Figure 3.9 depicts a graphical sketch of the 457

“decision view” [103, 191] in which design decisions are attached in the “4 + 1” 458

view model [188]. 459

Unc

orre

cted

Pro

of


54 P. Kruchten

Fig. 3.8 Impact analysis, starting from decision #11 [203]

DeploymentView

Design Decisions

Logical View

ImplementationView

ProcesssView

Design DecisionsDesign Decisions

Design Decisions

Design DecisionsDesign Decisions

Use CaseView

Fig. 3.9 A decision view embedded in the 4+1 views (from [191])

Unc

orre

cted

Pro

of



3.5 Rationale, or, the Missing Glue 460

Rationale, that is, an explicit articulation of the reasoning, the motivation of the 461

choice implied by the decision, has been present in the mind of software architect 462

all along; it was explicit in the formula of Perry and Wolf in 1992 [250]. The ra- 463

tionale can range from a simple pointer to a requirement to an elaborate trade-off 464

analysis between alternative solutions. Often, it also has to show that various con- 465

straints or previous decisions are taken into account. But, in practice the effort to 466

develop tools to capture and manage design rationale has not been very successful, 467

as Jintae Lee eloquently described [200]. The primary reason is that capturing ratio- 468

nale, except for a handful of important decisions; it is too tedious and does not bring 469

any immediate benefits to the person doing the capture. The benefit is largely down 470

the line, weeks or months later and for stakeholders others than the decision maker. 471

We found that much of the rationale is actually captured by the relationship 472

between design decisions (DDs) and other elements, in particular by tracing DDs 473

to requirements (upstream), to other decisions (see above), and to elements in the 474

design and its implementation (downstream). 475

3.6 Metaphors 476

There is one constant, though, throughout the whole (short) history of software ar- 477

chitecture, and regardless of the formality of the approach: it is the systematic use 478

of metaphors to describe architectural elements an architectures. Metaphors give 479

meaning to form and help us ground our conceptual systems. A metaphor is a form 480

of language that compares seemingly unrelated subjects: a rhetorical trope that de- 481

scribes a first subject as being equal or very similar to a second object in some way. 482

A metaphor implies a source domain: the domain from which we draw metaphorical 483

expressions, and a target domain, which is the conceptual domain we try to under- 484

stand or to describe. The metaphor operates a cognitive transfer from the source to 485

the target; it says in essence: “<the target> is <the source>.” 486

In Metaphors we live by [197], Lakoff and Johnson describe metaphors as “a 487

matter of imaginative rationality.” They permit “an understanding of one kind of 488

experience in terms of another, creating coherence by virtue of imposing gestalts 489

that are structured by natural dimensions of experience. New metaphors are capable 490

of creating new understanding and, therefore, new realities.” (p. 235) 491

Metaphors are everywhere in software architecture. We use so-called ontologi- 492

cal metaphors to name things: “clients and servers”, “layers”, “pipes and filters”, 493

“department stores and shopping cart,” etc. We organize those using structural 494

metaphors that are often visual and spatial: “on top of”, “parallel to”, “aligned with”, 495

“foreground, background”, but include richer ones such as “network”, “web”, or 496

“hierarchy” [245]. We use a wide variety of containers: “packages”, “repositories”, 497

“libraries”, “volumes”, etc. In reality, in the target domain, i.e., in the memory of 498

Unc

orre

cted

Pro

of


56 P. Kruchten

a computer, we would not find any up, down, aligned, packaged, etc. everything is 499

pretty scattered around; just look at a “core dump” file. 500

A mapping is the systematic set of correspondence that exists between con- 501

stituent elements of the source and the target domains. It allows some limited 502

reasoning in the target domain by analogy and inference. In our case, the tar- 503

get domain – software architecture – is rather abstract, and we try to draw from 504

source domains that are much more concrete. Then we use inference patterns from 505

the source conceptual domain to reason about the target one. “Ay, there’s the rub, 506

for” we may abuse the inference or have a faulty inference. This leads to flawed 507

metaphors, where the analogy “breaks” and the meaning in the target domain (in 508

software) is confusing at best. It is also very common when we attempt to combine 509

multiple metaphors, drawing form different source domains. 510

Metaphors have been used to describe general organization of software systems; 511

they have played an important role in the object-oriented movement, and then were 512

really put at the center of the pattern movement. No reasonable pattern can be suc- 513

cessful that is not supported by an elegant metaphor [64, 130]. More recently Beck 514

in eXtreme Programming (XP) described a practice he called “metaphor” to con- 515

vey the concept of a simple summary of the architecture [38]. It is unfortunate that 516

this practice has been the least successful of XP. Beck should have boldly called it 517

Allegory: an extended metaphor in which a story is told to illustrate an important 518

attribute of the subject, or even a Parable! 519

3.7 Summary 520

To return to our premises: Why do we want to represent architectural knowledge 521

explicitly? We want to: 522

• Gain intellectual control over a sophisticated system’s enormous complexity. 523

• Ensure the continuity, allowing these large systems to more effectively evolve and 524

to be maintained. 525

• Transfer this knowledge to others. 526

More tactically, we want to be able to 527

• Analyze and evaluate architectures, implement them, evolve them, assess some 528

of their qualities 529

• Support planning, budgeting, or acquisition activities 530

The more this architectural knowledge is left implicit, the more difficult or risky 531

these activities will be. Moreover, we also want to be able to abstract some more 532

generic architectural knowledge out of our collective knowledge in a given domain 533

or with given technologies. This knowledge is a combination of the following. 534

1. Architectural design, generic, brought in by using expert architects, educa- 535

tion, framework, methods, and standards. They are templates, exemplars of our 536

models. 537

Unc

orre

cted

Pro

of



2. Architectural design, for the system under development, expressed using a com- 538

bination of appropriate notations and tools, adapted to the concerns of the various 539

parties involved (viewpoints). They are models of the system. 540

3. Architectural decisions, for the system under development, with their complex 541

interdependencies, and tracing upstream to requirements, context, and con- 542

straints, and tracing downstream to the design, and even the implementation. 543

They explain why the models are the way they are. 544

Documents

Chapter 3 Documentation of Software Architecture from a ...courses.ece.ubc.ca/417/public/Chap-3.pdf · Documentation of Software Architecture 2 ... Per Brinch Hansen, ... and Wolf