1. Software Design and Architecture Muhammad Nasir Software Architecture Documentation m.nasir@iiu.edu.pk

2. Agenda Uses of Software Architecture Documentation Different Documentation Techniques Software Architecture Views Kruchten: “4+1” approach

3. Goal(s) with this lecture Previous Lectures  What is a Software Architecture  Why Software Architecture  What drives a Software Architecture  Software Architecture and Quality Goals of This Lecture  How to Document a Software Architecture

4. Different Documentation Techniques Boxes and lines Structured diagrams Formal specification Architecture Description Language (ADL)

5. Boxes and lines: Classic

6. Boxes and lines: Questions that need answers What are the nature of the boxes? Which computations do they represent? Do the boxes have similar behavior? What is the significance of the lines?  Data? Control? How do the behavior of the parts contribute to the behavior of the system? Does the layout have any meaning? How does the architecture operate at runtime?  Distribution  Multi processor systems

7. Structured Diagrams Add semantics to boxes and lines diagrams!  Provide a legend Example: Architectural style- specific notation  Pipes & filters: Now we know:  Boxes are filters, representing computational entities  Rounded boxes are pipes, controlling data flow  Arrows denote a use relationship

8. Structured Diagrams Siemens Four View model (Hofmeister et al.) uses Notation is irrelevant!  Booch, OMT, UML... Consistent use is most important!

9. Formal Specification E.g. mathematical specification Advantages:  Avoids ambiguities  Produces precise behavioral models  Permits rigorous analyses Example: Z, VDM

10. Architecture description language

11. Problems with ADLs No ADL provides the facilities to completely document an architecture! Hard to combine different ADLs Requires substantial investments:  Education  Install tools

12. What Is relevant to Present Functional Decomposition  Where do functionality belong Module Decomposition  What logical units fit together Execution Decomposition  Distribution across machines Code Representation  What files are there, and what versions

13. Views

14. “A software architecture is a complex entity that cannot be described in a simple one-dimensional fashion.”  Documenting Software Architectures (2002) No view is the architecture – all views convey it!  Each view focuses on certain aspects of the system. Which are the relevant views to use?  Different views expose different quality attributes to different degrees! Examples:  Kruchten, 1995: the “4+1” approach  Hofmeister et al.: Siemens Four View model

15. Kruchten: “4+1” approach Kruchten, 1995 Four main views:  Logical  Process  Development  Physical  +1 view: Scenarios Developed in large software projects Directed towards object-oriented development UML fits well!

16. Kruchten: “4+1” approach

17. Kruchten: Logical View Focus  Domain objects, key concepts Concepts  Classes, interfaces, relations UML  Static: Class/Object diagrams  Dynamic: Sequence/collaboration diagrams Interests  Functionality, Domain Representation Stakeholders  Domain experts, developers

18. Kruchten: Process View Focus  Concurrency, synchronization Concepts  Processes, threads, signals UML  As with focus on synchronization, etc. Activity Diagram Interests  Performance, Scalability, Availability, etc. Stakeholders  Developers, System Integrators

19. Kruchten: Development View Focus  Development units Concept  Subsystems, components, Packages, etc. UML  Package diagram, Component diagram Interests  Portability Stakeholders  Developers, Project Managers

20. Kruchten: Physical View Focus  Mapping to hardware, distribution Concepts  Deployment units, nodes, networks etc. UML  Deployment diagram Interests  Availability, Reliability, Performance, Scalability Stakeholders  System administrators, service staff

21. Kruchten: scenario view (+1) Focus  Functionality, correspondence among views Concepts  Use cases, scenarios UML  Use case diagrams, dynamic diagrams Interests  Functionality  Consistency Stakeholders  End users, architects  Developers

22. Siemens Four View Model Similar to Kruchten 4+1 Conceptual View (=Logical View) Module View (=Development View) Execution View (=Process View and Physical View) Code View (=???) Global Analysis (≈Scenarios) Hofmeister et al., 1999

23. Conceptual View Engineering Concerns  How does the system fulfill the requirements?  How are COTS components to be integrated? How do they interact with the rest of the system?  How is domain specific hardware and/or software incorporated into the system?  How is functionality partitioned into product releases?  How does the system incorporate portions of the prior generations of the product and how will it support future generations?  How are product lines supported?  How can the impact of changes in requirements be minimized?

24. Module View Engineering Concerns  How is the product mapped to the software platform?  What system support/services does it use, and exactly where?  How can testing be supported?  How can dependencies between modules be minimized?  How can reuse of modules and subsystems be maximized?  What techniques can be used to insulate the product from changes in COTS software, in the software platform, or changes to standards?

25. Execution View Engineering Concerns  How does the system meet its performance, and recovery requirements?  How can one balance resource usage (for example, load balancing)?  How can one achieve the necessary concurrency, replication and distribution without adding too much complexity to the control algorithms?  How can the impact of changes in the runtime platform be minimized?

26. Code View Engineering Concerns  How can the time and effort for product upgrades be reduced?  How should product versions and releases be managed?  How can build time be reduced?  What tools are needed to support the development environment?  How are integration and testing supported?

27. Putting views together

28. Two discussion questions Think of a technical document that you remember as being exceptionally useful!  What made it so? Think of a technical document that you remember as being dreadful!  What made it so?

29. Some Rules for Writing Good Documentation

30. Good Documentation Rules ! Rule 1: Write documentation from the reader’s point of view A document is written once, read several times.  Optimize for ”efficiency”! It is the most polite thing to do. A document written for the reader will be read. Avoid unnecessary jargon!

31. Good Documentation Rules ! Rule 2: Avoid unnecessary repetition Record information in one place only.  Makes the documentation easier to use!  Makes the documentation easier to change! But:  Could repeat for clarity...  Could repeat for making a different point... If repetition lowers the reader’s cost, do it!

32. Good Documentation Rules ! Rule 3: Avoid ambiguity Architecture design suppresses certain details.  Does this make the design ambiguous? Unplanned ambiguity occurs  When documentation can be interpreted in more than one way, and  When at least one of the ways is incorrect! Fight ambiguity with a well-defined notation.  Explain the notation used!

33. Good Documentation Rules ! Rule 4: Use a standard Organization Establish a standard, planned Organization scheme! Stick to it! Helps... ...the reader navigate and search the documentation. ...the writer plan and organize the contents. ...to ensure completeness.

34. Good Documentation Rules ! Rule 5: Record rationale Do not only document design decisions:  Also document why the decision was made.  Document the alternatives that were rejected. The rationale is important for redesign, maintenance etc.

35. Good Documentation Rules ! Rule 6: Keep documentation current, but not too current Change/update the documentation as you make changes. Incomplete/out-of-date documentation serves no purpose. Do not... ...update documentation with non-persistent decisions. ...update for every little design decision!

36. Good Documentation Rules ! Rule 7: Review documentation for fitness of purpose Who determines whether a document contains the right information?  The reader/audience!

37. Good Documentation Rules ! Don’t create a fifty-page document when a five-page will do! It’s always possible to go back to the whiteboard!  Time wasted on unnecessary documentation is lost!  Avoid low-value (to the customer) activities such as writing detailed documentation Have a realistic, workable architecture rather than merely well documented one!

38. The End Thanks for listening Questions would be appreciated.