Your SlideShare is downloading. ×
0
Documenting Software
Architectures
Introduction
• Architecture is the conceptual glue that holds every
  phase of the project together for all of its many
  ...
Uses of Architectural Document
• Documentation is decidedly not a case of "one size fits
  all."
• It should be sufficient...
Uses of Architectural Document
• One of the most fundamental rules for technical
  documentation is to write from the poin...
Uses of Architectural Document
Stakeholder                  Use
Architect and requirements   To negotiate and make tradeof...
Uses of Architectural Document
Stakeholder                     Use
Quality attribute specialists   To provide the model th...
Views
• Recall that we defined a software architecture
  for a system as
  The structure or structures of the system, whic...
Views
• This principle is useful because it breaks the
  problem of architecture documentation into
  more tractable parts...
Choosing the Relevant Views
• What are the relevant views?
 ▫ This is where knowing your stakeholders and the
   uses they...
Choosing the Relevant Views




                                                                                          ...
Choosing the Relevant Views
• Here is a simple three-step procedure for choosing
  the views for your project.
1. Produce ...
Choosing the Relevant Views
• For example
 ▫ The implementation view is often easily overlaid
   with the module decomposi...
Choosing the Relevant Views
3. Prioritize
  ▫   Decide what to do first
  ▫   How you decide depends on the details specif...
Documenting a View
• There is no industry-standard template for
  documenting a view, but the seven-part standard
  organi...
Primary presentation
• The primary presentation should contain the
  information you wish to convey about the
  system
• T...
Element catalog
• details at least those elements and relations
  depicted in the primary presentation
• Explains sufficie...
Context diagram
• shows how the system depicted in the view
  relates to its environment in the vocabulary of
  the view.
...
Variability guide
• shows how to exercise any variation points that are a
  part of the architecture shown in this view.
•...
Architecture background
• explains why the design reflected in the view came
  to be.
• The goal of this section is to exp...
Documenting Interfaces
• An interface is a boundary across which two
  independent entities meet and interact or communica...
Documentation across Views
• Cross-view document capture the information that
  applies to more than one view.
• Cross-vie...
Template for Documenting Interfaces
• Here is a suggested standard organization for
  interface documentation.
1. Interfac...
Template for Documenting Interfaces
• Interface identity.
  ▫ When an element has multiple interfaces, identify
    the in...
Template for Documenting Interfaces
• Resource semantics: This describes the result of
  invoking the resource. It might i...
Template for Documenting Interfaces
• Data type definitions
  ▫ The architect should communicate the definition of
    dat...
Template for Documenting Interfaces
• Quality attribute characteristics of the interface
  ▫ This information may be in th...
Template for Documenting Interfaces
• Usage guide
 ▫ In some cases semantics need to be reasoned
   about in terms of how ...
Documentation across Views
• How the document is organized:
  1. View catalog
  2. View template
• What the architecture i...
View Catalog
• A view catalog is the reader's introduction to the
  views
• Each entry in catalog contains
 ▫ The name of ...
View Template
• A view template is the standard organization for
  a view.
• It helps a reader navigate quickly to a secti...
What the Architecture is
• System Overview
   This is a short prose description of what the
  system's function is, who it...
What the Architecture is
• Element List
   The element list is simply an index of all of the
  elements that appear in any...
Why the Architecture is the way it is
• Cross-view rationale explains how the overall
  architecture is in fact a solution...
Unified Modeling Language (UML)
• Today the Unified Modeling Language (UML) has
  emerged as the de facto standard notatio...
UML - Module Views
• Interfaces in UML
UML - Module Views
• Examples of module notations in UML
UML - Module Views
• Decomposition in UML with nesting
UML - Module Views
• A simple representation of layers in UML
UML-Component and Connector Views
• Five ways to represent interfaces to components
UML-Component and Connector Views
• Systems as collaborations
UML-Allocation Views
• A deployment view in UML
Summary
• An architecture is worthless if nobody can
  understand what it is or how to use it
• You must understand the st...
Upcoming SlideShare
Loading in...5
×

Software archiecture lecture09

552

Published on

Published in: Education
0 Comments
1 Like
Statistics
Notes
  • Be the first to comment

No Downloads
Views
Total Views
552
On Slideshare
0
From Embeds
0
Number of Embeds
0
Actions
Shares
0
Downloads
28
Comments
0
Likes
1
Embeds 0
No embeds

No notes for slide

Transcript of "Software archiecture lecture09"

  1. 1. Documenting Software Architectures
  2. 2. Introduction • Architecture is the conceptual glue that holds every phase of the project together for all of its many stakeholders. • Documenting the architecture is the crowning step to crafting it • Even a perfect architecture is useless if no one understands it • You must describe Architecture in sufficient detail, without ambiguity, and organized in such a way that others can quickly find needed information. • This chapter will help you decide what information about an architecture is important to capture, and it will discuss guidelines for capturing it. It will also discuss notations that are available, including UML.
  3. 3. Uses of Architectural Document • Documentation is decidedly not a case of "one size fits all." • It should be sufficiently abstract to be quickly understood by new employees but sufficiently detailed to serve as a blueprint for analysis. • We should not expect to produce one architectural document and have every consumer read it in the same way. • Rather, we should produce documentation that helps a stakeholder quickly find the information that stakeholder is interested in, with a minimum of information that is irrelevant (to that stakeholder) standing in the way. • This might mean producing different documents for different stakeholders.
  4. 4. Uses of Architectural Document • One of the most fundamental rules for technical documentation is to write from the point of view of the reader. • Understanding who the stakeholders are and how they will want to use the documentation will help us organize it and make it accessible to and usable for them
  5. 5. Uses of Architectural Document Stakeholder Use Architect and requirements To negotiate and make tradeoffs among competing requirements engineers who represent customer(s) Architect and designers of To resolve resource contention and establish performance and other kinds of runtime resource consumption budgets constituent parts Implementors To provide inviolable constraints (plus exploitable freedoms) on downstream development activities Testers and integrators To specify the correct black-box behavior of the pieces that must fit together Maintainers To reveal areas a prospective change will affect Designers of other systems To define the set of operations provided and required, and the protocols for their operation with which this one must interoperate
  6. 6. Uses of Architectural Document Stakeholder Use Quality attribute specialists To provide the model that drives analytical tools such as simulations and simulation generators, theorem provers, verifiers, etc. These tools require information about resource consumption, scheduling policies, dependencies, and so forth. Architecture documentation must contain the information necessary to evaluate a variety of quality attributes such as security, performance, usability, availability, and modifiability. Analyses for each attributes have their own information needs. Managers To create development teams corresponding to work assignments identified, to plan and allocate project resources, and to track progress by the various teams Product line managers To determine whether a potential new member of a product family is in or out of scope, and if out by how much Quality assurance team To provide a basis for conformance checking, for assurance that implementations have been faithful to the architectural prescriptions
  7. 7. Views • Recall that we defined a software architecture for a system as The structure or structures of the system, which comprise elements, the externally visible properties of those elements, and the relationships among them." • The concept of a view, which you can think of as capturing a structure, provides us with the basic principle of documenting software architecture: Documenting an architecture is a matter of documenting the relevant views and then adding documentation that applies to more than one view.
  8. 8. Views • This principle is useful because it breaks the problem of architecture documentation into more tractable parts, which provide the structure for the remainder of this chapter: ▫ Choosing the relevant views ▫ Documenting a view ▫ Documenting information that applies to more than one view
  9. 9. Choosing the Relevant Views • What are the relevant views? ▫ This is where knowing your stakeholders and the uses they plan to make of the documentation will help you construct the documentation package they need. • The views you should document depend on the uses you expect to make of the documentation
  10. 10. Choosing the Relevant Views Implementation Decomposition Deployment Layer Class Uses C&C Stakeholder Project Manager s s s d Member of Development Team d d d d d s s Testers and Integrators d d s s s Maintainers d d d d d s s Product Line Application Builder d s o s s s Customer s o End User s s Analyst d d s d s d Infrastructure Support s s s s d New Stakeholder x x x x x x x Current and Future Architect d d d d d d s Key: d = detailed information, s = some details, o = overview information, x = anything
  11. 11. Choosing the Relevant Views • Here is a simple three-step procedure for choosing the views for your project. 1. Produce a candidate view list ▫ Begin by building a stakeholder/view table, like Table 9.2. 2. Combine views ▫ The candidate view list from step 1 is likely to yield an impractically large number of views ▫ See if the stakeholders could be equally well served by another view having a stronger constituency ▫ look for views that are good candidates to be combined
  12. 12. Choosing the Relevant Views • For example ▫ The implementation view is often easily overlaid with the module decomposition view. ▫ The module decomposition view also pairs well with uses or layered views. ▫ The deployment view usually combines well with whatever component-and-connector view shows the components that are allocated to hardware elements—the process view.
  13. 13. Choosing the Relevant Views 3. Prioritize ▫ Decide what to do first ▫ How you decide depends on the details specific to your project. ▫ A project manager demands attention and information early and often
  14. 14. Documenting a View • There is no industry-standard template for documenting a view, but the seven-part standard organization that we suggest in this section has worked well in practice 1. Primary presentation 2. Element catalog 3. Context diagram 4. Variability guide 5. Architecture background 6. Glossary of terms 7. Other information • Allocating specific information to specific sections will help the documentation writer attack the task and recognize completion
  15. 15. Primary presentation • The primary presentation should contain the information you wish to convey about the system • The primary presentation is usually graphical and accompanied by explanation of the notation or symbol used. • Sometimes the primary presentation can be tabular
  16. 16. Element catalog • details at least those elements and relations depicted in the primary presentation • Explains sufficient detail what elements are, and their purposes or the roles they play, rendered in the vocabulary of the view. • In addition, if there are elements or relations relevant to the view that were omitted from the primary presentation, the catalog is where those are introduced and explained
  17. 17. Context diagram • shows how the system depicted in the view relates to its environment in the vocabulary of the view. • For example, in a component-and-connector view you show which component and connectors interact with external components and connectors, via which interfaces and protocols.
  18. 18. Variability guide • shows how to exercise any variation points that are a part of the architecture shown in this view. • In some architectures, decisions are left unbound until a later stage of the development process • Variability guide should include: 1. the options among which a choice is to be made. ▫ In a module view, the options are the various versions or parameterizations of modules. ▫ In a component-and-connector view, they might include constraints on replication, scheduling, or choice of protocol. ▫ In an allocation view, they might include the conditions under which a software element would be allocated to a particular processor. 2. the binding time of the option. Some choices are made at design time, some at build time, and others at runtime
  19. 19. Architecture background • explains why the design reflected in the view came to be. • The goal of this section is to explain to someone why the design is as it is and to provide a convincing argument that it is sound. • An architecture background includes 1. rationale, explaining why the decisions reflected in the view were made and why alternatives were rejected. 2. analysis results, which justify the design or explain what would have to change in the face of a modification. 3. assumptions reflected in the design.
  20. 20. Documenting Interfaces • An interface is a boundary across which two independent entities meet and interact or communicate with each other • Since you cannot perform analyses or system building without them, documenting interfaces is an important part of documenting architecture. • Documenting an interface consists of naming and identifying it and documenting its syntactic and semantic information • An interface is documented with an interface specification • Documenting an interface is a matter of striking a balance between disclosing too little information and disclosing too much. • A rule of thumb is to focus on how elements interact with their operational environments,
  21. 21. Documentation across Views • Cross-view document capture the information that applies to more than one view. • Cross-view documentation consists of just three major aspects, which we can summarize as how-what-why • How the documentation is laid out and organized so that a stakeholder can find the information efficiently and reliably. • What the architecture is. Here, the information that remains to be captured beyond the views themselves. • Why the architecture is the way it is: the context for the system, external constraints that have been imposed to shape the architecture in certain ways, and the rationale for coarse-grained large-scale decisions
  22. 22. Template for Documenting Interfaces • Here is a suggested standard organization for interface documentation. 1. Interface Identity 2. Resources provided 2.1 Resource syntax 2.2 Resource semantics 2.3 Resource usage restrictions 3. Locally defined data types 4. Exception definitions 5. Variability provided 6. Quality attribute characteristics 7. Element requirements 8. Rationale and design issues 9. Usage guide
  23. 23. Template for Documenting Interfaces • Interface identity. ▫ When an element has multiple interfaces, identify the individual interfaces to distinguish them. ▫ You may also need to provide a version number • Resource syntax ▫ The signature includes any information another program will need to write a syntactically correct program that uses the resource. ▫ The signature includes the resource name, names and logical data types of arguments (if any), and so forth.
  24. 24. Template for Documenting Interfaces • Resource semantics: This describes the result of invoking the resource. It might include ▫ Assignment of values to data that the actor invoking the resource can access (Where and How are values come from) ▫ Events that will be signaled or messages that will be sent as a result of using the resource ▫ How other resources will behave in the future as the result of using this resource. ▫ Humanly observable results. • Resource usage restrictions. ▫ Under what circumstances may this resource be used
  25. 25. Template for Documenting Interfaces • Data type definitions ▫ The architect should communicate the definition of data type that not provided by the underlying programming language • Exception definitions ▫ These describe exceptions that can be raised by the resources on the interface. • Variability provided by the interface ▫ configuration parameters and how they affect the semantics of the interface must be documented ▫ These configuration parameters and how they affect the semantics of the interface must be documented.
  26. 26. Template for Documenting Interfaces • Quality attribute characteristics of the interface ▫ This information may be in the form of constraints on implementations of elements that will realize the interface • Element requirements. ▫ What the element requires may be specific, named resources provided by other elements. • Rationale and design issues. ▫ The architect should record the reasons for an element's interface design. ▫ The rationale should explain the motivation behind the design, constraints and compromises what alternative designs were considered and rejected.
  27. 27. Template for Documenting Interfaces • Usage guide ▫ In some cases semantics need to be reasoned about in terms of how a broad number of individual interactions interrelate ▫ Essentially, a protocol is involved that is documented by considering a sequence of interactions. ▫ Protocols can represent the complete behavior of the interaction or patterns of usage that the element designer expects to come up repeatedly.
  28. 28. Documentation across Views • How the document is organized: 1. View catalog 2. View template • What the architecture is: 1. System overview 2. Mapping between views (the way the views are related to each other) 3. List of elements and where they appear 4. Project glossary • Why the architecture is the way it is: 1. Rationale
  29. 29. View Catalog • A view catalog is the reader's introduction to the views • Each entry in catalog contains ▫ The name of the view and what style it instantiates ▫ A description of the view's element types, relation types, and properties ▫ A description of what the view is for ▫ Management information about the view document, such as the latest version, the location of the view document, and the owner of the view document
  30. 30. View Template • A view template is the standard organization for a view. • It helps a reader navigate quickly to a section of interest, and it helps a writer organize the information and establish criteria for knowing how much work is left to do.
  31. 31. What the Architecture is • System Overview This is a short prose description of what the system's function is, who its users are, and any important background or constraints • Mapping between Views It’s reasonable that any two views will have much in common (describe same thing) Helping a reader of the documentation understand the relationships among views will give him a powerful insight into how the architecture works as a unified conceptual whole.
  32. 32. What the Architecture is • Element List The element list is simply an index of all of the elements that appear in any of the views, along with a pointer to where each one is defined. • Project Glossary The glossary lists and defines terms unique to the system that have special meaning
  33. 33. Why the Architecture is the way it is • Cross-view rationale explains how the overall architecture is in fact a solution to its requirements. • the implications of system-wide design choices on meeting the requirements or satisfying constraints. • the effect on the architecture when adding a foreseen new requirement or changing an existing one. • the constraints on the developer in implementing a solution. • decision alternatives that were rejected.
  34. 34. Unified Modeling Language (UML) • Today the Unified Modeling Language (UML) has emerged as the de facto standard notation for documenting a software architecture. • It is up to the architect to augment the UML pictures with the necessary supporting documentation • UML provides no direct support for components, connectors, layers, interface semantics, or many other aspects of a system that are supremely architectural.
  35. 35. UML - Module Views • Interfaces in UML
  36. 36. UML - Module Views • Examples of module notations in UML
  37. 37. UML - Module Views • Decomposition in UML with nesting
  38. 38. UML - Module Views • A simple representation of layers in UML
  39. 39. UML-Component and Connector Views • Five ways to represent interfaces to components
  40. 40. UML-Component and Connector Views • Systems as collaborations
  41. 41. UML-Allocation Views • A deployment view in UML
  42. 42. Summary • An architecture is worthless if nobody can understand what it is or how to use it • You must understand the stakeholders of the architecture and how they expect to use the documentation • Treat the task of documenting an architecture as documenting the set of relevant views and then supplementing that with cross-view information • Box-and-line diagrams tell only a small part of the story • Supporting documentation that explains the elements and relationships shown in diagrams are important parts
  1. A particular slide catching your eye?

    Clipping is a handy way to collect important slides you want to go back to later.

×