Why Documenting Software Architecture is Important

1
Why Documenting Software Architecture is
Important UML Defined

• By
• Michael Tominello
• (08B1779354)
• for
• CTU CS644
• Professor Scott Puryear
• November 4, 2008

2
The Importance of Documenting Software
Architecture

• Software Architecture Defined
• Communication Among Stake Holders
• Early Design Decisions
• Defines Constraints on Implementation
• Dictates organizational Structure
• Inhibits or Enables System Quality Attributes
• Allows the System Qualities to be Predicted
• Allows for Change to be Understood and Managed
• Helps Evolutionary Prototyping
• Allows for More Accurate Cost and Schedule
  Estimation
• Transferable Abstraction of a System
• Method of Documentation
• UML

(Bass P. 26)
3
Software Architecture

• The software architecture of a program or
  computing system is the structure or structures
  of the system, which comprise software
  components, the externally visible properties of
  those components and the relationship among them
  (Bass p.21)

Multiplication
Function Manager
Division
Addition
Subtraction
4
Communication Among Stake Holders

• SW Architecture represents a common picture of
  the system that most stakeholders can
  understand, thus allowing for
• Communication
• Depicts various system characteristics, thus
  addressing various stakeholder interests
• Negotiation
• Stakeholders have a clear understanding of the
  system capabilities and can clearly negotiate the
  capabilities based on time, money and priorities
• Consensus
• All stakeholders can agree on the system
  capabilities and structure

(Bass p.27)
5
Early Design Decisions

• Defines Constraints on Implementation
• Dictates organizational Structure
• Inhibits or Enables System Quality Attributes
• Allows the System Qualities to be Predicted
• Allows for Change to be Understood and Managed
• Helps Evolutionary Prototyping
• Allows for More Accurate Cost and Schedule
  Estimation

(Bass p.29 - 32)
6
Defines Constraints on Implementation

• The constraints are carried into the
  implantation of the architecture
• Allows the parts of architecture to be clearly
  defined
• Allows groups to work on assigned parts w/o much
  concern to other parts

Team F
Team B
Team E
Team A
Team C
Team D
6
(Bass p. 29 - 32)
7
Dictates organizational Structure

• The organization structure can be divided into
  groups and assigned to different part of the
  architecture
• e.g. SW Software, databases, infrastructure etc
• Allows schedule to be assigned by parts of
  architecture
• Allows budgets to be assigned by parts of
  architecture
• Allows costs to be collected by parts of
  architecture

Architecture Team
Software Team
Infrastructure Team
Database Team
(Bass p. 29)
8
Inhibits or Enables System Quality Attributes

• Performance as Priority
• Limit interaction and volume between components
• Modifiability as Priority
• Design components to be encapsulated as allowable
• Security as Priority
• Manage/protect component communication access
• Scalability as Priority
• Localize use of resources to allow replacement of
  higher capacity elements

(Bass p. 30)
9
Allows the System Qualities to be Predicted

• The architecture documentation allows
  architecture evaluation techniques to be applied
  such as ATAM, CBAM, SAAM, ARID, etc

(Bass p. 31)
10
Allows Change to be Understood Managed

• Approximately 80 of system costs are incurred
  after initial deployment
• Most developers never work on a new system
• Designing the system to accept change with ease
  can result in large savings over the life of the
  SW
• Time spent documenting analyzing and adjusting
  the architecture up from has large pay-offs over
  time

(Bass p.31)
11
Helps Evolutionary Prototyping

• The Architecture documentation can be used as a
  road map to develop a prototype of the system
• The prototype can be incrementally enhanced to
  contain more and more functionality over time
  allowing for concepts, designs and performance
  criteria to evolve

(Bass p.31)
12
More Accurate Cost Schedule Estimation

• The architecture documentation can be used to
  gain a better understanding of the cost and
  schedule required to complete the system
• The architecture components can be broken down
  into smaller pieces that allow the system to be
  better understood and estimated

(Bass p.32)
13
Transferable Abstraction of a System

• Documenting the architecture prior to
  implementation can be as important as having
  current architecture documentation at the end of
  the project
• This allows the architecture to be applied,
  partially or completely, to other solutions
• This allows organizations to gain efficiencies
  and improve productivity

(Bass p.32)
14
UML Defined

• According to Wikipedia Unified Modeling Language
  (UML) is a standardized general-purpose modeling
  language in the field of software engineering.
  UML includes a set of graphical notation
  techniques to create abstract models of specific
  systems, referred to as UML model.
• Bass (2003) states that Unified Modeling
  Language has emerged as the de-facto standard
  notation for documenting a software architecture
  (p. 218).
• Primary contribution is at top-level
  documentation
• Secondary contribution at the behavior of
  elements
• Not necessarily easy to understand for
  non-techies
• Clements (2002) states that It was originally
  constructed as a language to support
  object-oriented design and analysis, not as an
  ADL. As such does not include architectural
  concepts (layers, for instance) as first Class
  entities (p.10)

(Bass p.32)
15
UML Defined, continued

• According to Wikipedia
• The Unified Modeling Language (UML) is a
  graphical language for visualizing, specifying
  and constructing the artifacts of a
  software-intensive system. The Unified Modeling
  Language offers a standard way to write a
  system's blueprints, including conceptual things
  such as business processes and system functions
  as well as concrete things such as programming
  language statements, database schemas, and
  reusable software components.
• Methods UML is not a method in and of itself.
  It is capable of representing various
  architectural methods (for example OMT, Booch
  method, Objectory) (wikipedia)

http//en.wikipedia.org/wiki/Unified_Modeling_Lang
uage
16
UML Modeling

• UML provides portions of the SW documentation
  though diagrams - According to Wikipedia
• Functional requirements view Focuses on the
  functional requirements of the system from the
  user's point of view. And includes use case
  diagrams.
• Static structural view Emphasizes the static
  structure of the system using objects,
  attributes, operations and relationships. And
  includes class diagrams and composite structure
  diagrams
• Dynamic behavior view Emphasizes the dynamic
  behavior of the system by showing collaborations
  among objects and changes to the internal states
  of objects. And includes sequence diagrams,
  activity diagrams and state machine diagrams

http//en.wikipedia.org/wiki/Unified_Modeling_Lang
uage
17
UML Types of Diagrams

• According to Wikipedia
• UML 2.0 has 13 types of diagrams in 3 Catagories
• Six diagram types represent static application
  structure
• Three represent general types of behavior
• Four represent different aspects of interactions

http//en.wikipedia.org/wiki/Unified_Modeling_Lang
uage
18
Structure Diagrams

• Structure diagrams emphasize what things must be
  in the system being modeled - according to
  Wikipedia
• Class diagram structure of a system by showing
  the system's classes, their attributes, and the
  relationships between the classes.
• Component diagram depicts how a SW system is
  split into components and shows the dependencies
  among these components.
• Composite structure diagram describes the
  internal structure of a class and the
  collaborations that this structure makes
  possible.
• Deployment diagram the hardware implementations,
  the components deployed on hardware the
  associations between those components.
• Object diagram shows a complete or partial view
  of the structure of a modeled system at a
  specific time.
• Package diagram depicts how a system is split up
  into logical groupings by showing the
  dependencies among these groupings.

http//en.wikipedia.org/wiki/Unified_Modeling_Lang
uage
19
Structure Diagrams Continued
http//en.wikipedia.org/wiki/Unified_Modeling_Lang
uage
20
Behavior Diagrams

• Behavior diagrams emphasize what must happen in
  the system being modeled - according to Wikipedia
• Activity diagram represents the business and
  operational step-by-step workflows of components.
  An activity diagram shows the overall flow of
  control.
• State diagram standardized notation to describe
  many systems, from computer programs to business
  processes.
• Use case diagram shows the functionality
  provided by a system in terms of actors, their
  goals represented as use cases, and dependencies
  between those use cases.

http//en.wikipedia.org/wiki/Unified_Modeling_Lang
uage
21
Behavior Diagrams Continued
http//en.wikipedia.org/wiki/Unified_Modeling_Lang
uage
22
Interaction Diagrams

• Interaction diagrams are a subset of behavior
  diagrams, emphasize the flow of control and data
  among the things in the system being modeled
  according to wikipedia
• Communication diagram shows the interactions
  between objects terms of sequenced messages. They
  represent a combination of information taken from
  Class, Sequence, and Use Case Diagrams describing
  the static structure and dynamic behavior of a
  system.
• Interaction overview diagram a type of activity
  diagram in which the nodes represent interaction
  diagrams.
• Sequence diagram shows how processes operate
  with one another and in what order.
• Timing diagrams are a specific type of
  interaction diagram, where the focus is on timing
  constraints.

http//en.wikipedia.org/wiki/Unified_Modeling_Lang
uage
23
Interaction Diagrams Continued
http//en.wikipedia.org/wiki/Unified_Modeling_Lang
uage
24
Closing

• An Information Manager would use the
  documentation of software architecture to confirm
  that all stakeholders agree on the system, that
  the teams can implement the system to meet the
  system requirements and to be able to reuse the
  system on other problem spaces.
• An Information Manager would use UML to document
  certain aspect of the system Functional
  requirements views, Static structural view and
  Dynamic behavior views.
• Where you can go for more information
• Documenting SW Architecture
• Carnegie Mellon Software Engineering Institute
• UML
• Wikipedia
• UML Object Modeling Group

25
Questions For Me
26
Questions For You

• Name
• Why is it important to document SW Architecture?
• What stage of a computer system's lifecycle is
  the most costly , why and how cab the costs be
  reduced?
• How many types of diagrams does UML 2.o
  represent and what are the three categories of
  the diagrams?

27
References

• Bass, L., Clements, P., Kazman R. (2003) Software
  Architecture in Practice, Boston Addison-Wesley
• Clements, P., Kazman, R., Klein, M. (2003)
  Evaluating Software Architecture, Boston
  Addison-Wesley
• Wikipedia, retrieved from http//en.wikipedia.org/
  wiki/Unified_Modeling_Language, (November 2008)

http//en.wikipedia.org/wiki/Unified_Modeling_Lang
uage
28

• Back - Up

29
Criticism

• Language bloat
• Weak visualization
• Problems in learning and adopting
• Only the code is in sync with the code
• Cumulative Impedance/Impedance Mismatching
• Aesthetically Inconsistent
• Tries to be all things to all programmers
• Dysfunctional interchange format

http//en.wikipedia.org/wiki/Unified_Modeling_Lang
uage