Designing and documenting software architecture unit 5
Download as DOCX, PDF3 likes2,483 views
The document discusses architectural documentation. It covers views, which divide an architecture into manageable representations. Relevant views depend on usage and include module, component-and-connector, and allocation views. Each view has a template for documentation, including a primary presentation, element catalog, context diagram, variability guide, and rationale. Cross-view documentation explains the organization, what the architecture contains through a system overview and element list, and the rationale for design decisions. Architectural documentation aims to educate users, enable communication, and provide a basis for construction and analysis.
Designing and documenting software architecture unit 5
- 1. UNIT V (Designing and Documenting Software Architecture ) Covers: Architecture in the life cycle; Designing the architecture; forming the team structure; creating a skeletal system. Uses of architectural documentation; Views; choosing the relevant views; documenting a view; Documentation across views. Architecture in the Life Cycle The evolutionary delivery life cycle Get customer feedback Iterate through several releases, each with new or modified functionality Deliver limited versions if necessary When does one begin designing? Some idea of system requirements is needed – the shaping requirements are called architectural drivers Identify the highest priority business goals and turn them into quality scenarios or use cases The ones that have the most impact on the architecture are the architectural drivers (there should be fewer than 10) Once the architectural drivers are known, the architectural design can begin The requirements analysis process will then be influenced by questions generated during the architectural design, Evolutionary Delivery Life Cycle
- 2. Designing the Architecture • A method called Attribute Driven Design (ADD) can be used to design an architecture to satisfy both quality and functional requirements. • ADD can be viewed as an extension to other developments methods, such as the Rational Unified Process (RUP). Attribute-Driven Design • ADD bases the decomposition process on the quality attributes the software has to fulfill. • It is a recursive decomposition process, where, at each stage, tactics and architectural patterns are chosen to satisfy a set of quality scenarios and then functionality is allocated to instantiate the module types provided by the pattern. • The system is described as a set of containers for functionality and the interactions among them. • This is a coarse grained framework for achieving the functionality. Example Application of ADD • Sample problem: A garage door opener within a home information system. The system is responsible for raising and lowering the door via a switch, remote control, or the home information system. It is also possible to diagnose problems with the opener from within the home information system. Input to ADD • A set of requirements (typically expressed as use cases) and constraints • A set of quality requirements expressed as system-specific quality scenarios including, in this case: – The device and controls for opening and closing the door are different for the various products in the product line. They may include controls from within a home information system – The processor used in different products will differ. – If an obstacle (person or object) is detected by the garage door during descent, it must halt (alternately re-open) within 0.1 second. The garage door opener should be accessible for diagnosis and administration from within the home information system using a product-specific diagnosis protocol. (Continued .. lol Skipped) ADD Steps: 1. Choose the module to decompose – the module to start with is usually the whole system. 2. Refine the module according to the following steps: a. Choose the architectural drivers from the set of concrete quality scenarios and functional requirements. b. Choose an architectural pattern that satisfies the architectural drivers based on the tactics that can be used to achieve the drivers. c. Instantiate modules and allocate functionality from the use cases and represent using multiple views. d. Define interfaces of the child modules. The decomposition provides modules and constraints on the types of module interactions. Document this information in the interface document for each module. e. Verify and refine use cases and quality scenarios and make them constraints for child modules. 3. Repeat the steps above for every module that needs further decomposition.
- 3. Forming the Team Structure • Once the first few levels of the architecture’s module decomposition structure are fairly stable, those modules can be allocated to development teams. • Within teams there needs to be high-bandwidth communications. Between teams, low-bandwidth communications are sufficient (and in fact crucial). • If interactions between the teams is complex, either: – The interactions among the elements they are creating are needlessly complex – Or, the requirements for those elements were not sufficiently “hardened” before development commenced • Like software systems, teams should strive for high cohesion(forming a united whole) and low coupling (the pairing of two items). • Each module of the system constitutes its own small domain (area of specialized knowledge or expertise). • This makes for a natural fit between teams and modules of the decomposition structure. • The effective use of staff, therefore, is to assign members to a team based on their expertise. • The organizational structure also affects the architecture. • Organizational entities formed for one project are motivated to preserve their existence and will want to maximize their importance in new projects. Creating a Skeletal System • Once an architecture is sufficiently designed and teams are in place to build it, a skeletal system can be constructed. • The architecture provides a guide as to the order in which portions of the system should be implemented. – First implement the software that deals with the execution and interaction of architectural components. – Add some simple functions. • The result is a running system onto which useful functionality can be added • To lower risk the most problematic functions should be added first. • Then the functionality needed to support those problematic functions is added. • This process is continued, growing larger and larger increments of the system until it is complete.
- 4. Architecture Documentation • Even the best architecture will be useless if the people who need it – do not know what it is; – cannot understand it well enough to use, build, or modify it; – misunderstand it and apply it incorrectly. • All of the effort, analysis, hard work, and insightful design on the part of the architecture team will have been wasted. Uses of architectural documentation • Architecture documentation must – be sufficiently transparent and accessible to be quickly understood by new employees – be sufficiently concrete to serve as a blueprint for construction – have enough information to serve as a basis for analysis. • Architecture documentation is both prescriptive and descriptive. – For some audiences, it prescribes what should be true, placing constraints on decisions yet to be made. – For other audiences, it describes what is true, recounting decisions already made about a system’s design. • Understanding stakeholder uses of architecture documentation is essential • Those uses determine the information to capture. Three Uses for Architecture Documentation 1. Education • Introducing people to the system – New members of the team – External analysts or evaluators – New architect 2. Primary vehicle for communication among stakeholders • Especially architect to developers • Especially architect to future architect! 3. Basis for system analysis and construction • Architecture tells implementers what to implement. • Each module has interfaces that must be provided and uses interfaces from other modules. • Documentation can serve as a receptacle for registering and communicating unresolved issues. Architecture documentation serves as the basis for architecture evaluation.
- 5. Views • Views let us divide a software architecture into a number of (we hope) interesting and manageable representations of the system. • Principle of architecture documentation: – Documenting an architecture is a matter of documenting the relevant views and then adding documentation that applies to more than one view. Which Views? The Ones You Need! • Different views support different goals and uses. • We do not advocate a particular view or collection of views. • The views you should document depend on the uses you expect to make of the documentation. Each view has a cost and a benefit; you should ensure that the benefits of maintaining a view outweigh its costs. Choosing the relevant Views You can determine which views are required, when to create them, and how much detail to include if you know the following: – What people, and with what skills, are available – Which standards you have to comply with – What budget is on hand – What the schedule is – What the information needs of the important stakeholders are – What the driving quality attribute requirements are – What the approximate size of the system is At a minimum, expect to have at least one module view, at least one C&C view, and for larger systems, at least one allocation view in your architecture document Documenting a View • Section 1: The Primary Presentation. – The primary presentation shows the elements and relations of the view. – The primary presentation should contain the information you wish to convey about the system—in the vocabulary of that view. – The primary presentation is most often graphical. • It might be a diagram you’ve drawn in an informal notation using a simple drawing tool, or it might be a diagram in a semiformal or formal notation imported from a design or modeling tool that you’re using. • If your primary presentation is graphical, make sure to include a key that explains the notation. • Lack of a key is the most common mistake that we see in documentation in practice. – Occasionally the primary presentation will be textual, such as a table or a list. • If that text is presented according to certain stylistic rules, these rules should be stated or incorporated by reference, as the analog to the graphical notation key. • Section 2: The Element Catalog. – The element catalog details at least those elements depicted in the primary presentation. • For instance, if a diagram shows elements A, B, and C, then the element catalog needs to explain what A, B, and C are.
- 6. • If elements or relations relevant to this view were omitted from the primary presentation, they should be introduced and explained in the catalog. – Parts of the catalog: • Elements and their properties. This section names each element in the view and lists the properties of that element. Each view introduced in Chapter 1 listed a set of suggested properties associated with that view. • Relations and their properties. Each view has specific relation types that it depicts among the elements in that view. • Element interfaces. This section documents element interfaces. Element behavior. This section documents element behavior that is not obvious from the primary presentation • Section 3: Context Diagram. – A context diagram shows how the system or portion of the system depicted in this view relates to its environment. – The purpose of a context diagram is to depict the scope of a view. – Entities in the environment may be humans, other computer systems, or physical objects, such as sensors or controlled devices. • Section 4: Variability Guide. – A variability guide shows how to exercise any variation points that are a part of the architecture shown in this view. • Section 5: Rationale. – Rationale explains why the design reflected in the view came to be. – The goal of this section is to explain why the design is as it is and to provide a convincing argument that it is sound. – The choice of a pattern in this view should be justified here by describing the architectural problem that the chosen pattern solves and the rationale for choosing it over another. View Template
- 7. Documentation Across Views Cross-view documentation consists of just three major aspects, which we can summarize as how- what-why Summary of cross-view documentation How the documentation is organized to a stakeholder: Every suite of architectural documentation needs an introductory piece to explain its organization to a novice stakeholder and to help that stakeholder access the information he or she is most interested in. There are two kinds of "how" information: View Catalog A view catalog is the reader's introduction to the views that the architect has chosen to include in the suite of documentation. There is one entry in the view catalog for each view given in the documentation suite. Each entry should give the following: – 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 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. What the architecture is: This section provides information about the system whose architecture is being documented, the relation of the views to each other, and an index of architectural elements. 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. The intent is to provide readers with a consistent mental model of the system and its purpose. Sometimes the project at large will have a system overview, in which case this section of the architectural documentation simply points to that. Mapping between Views Since all of the views of an architecture describe the same system, it stands to reason that any two views will have much in common. Helping a reader of the documentation understand the relationships among views will give him a powerful insight into how the architecture works as a
- 8. unified conceptual whole. Being clear about the relationship by providing mappings between views is the key to increased understanding and decreased confusion. 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. This will help stakeholders look up items of interest quickly. Project Glossary The glossary lists and defines terms unique to the system that have special meaning. A list of acronyms, and the meaning of each, will also be appreciated by stakeholders. If an appropriate glossary already exists, a pointer to it will suffice here. Why the architecture is the way it is: Rationale Cross-view rationale explains how the overall architecture is in fact a solution to its requirements. One might use the rationale to explain: – 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. In general, the rationale explains why a decision was made and what the implications are in changing it.