Documenting and Designing Architectures Using Together

1
Documenting and Designing Architectures Using
Together
Tom Gullion lttom.gullion_at_borland.comgt
2
Communication

• Architecture is all about communication.
• Todays software systems are amazingly complex,
  requiring models as a way to illustrate the
  design to a wide variety of people.
• Architecture is well-known as a development best
  practice.

3
Good vs. Bad Architecture

• The major problem what makes an architecture
  good or bad?
• In general, the four goals of good design
• High cohesion
• Low coupling
• Evenly distributed behavior
• Strong modularity
• Charles Richter in Designing Flexible
  Object-Oriented Systems with UML, 1999, Macmillan
  Technical Publishing
• Perhaps what really separates good and bad
  architectures is more a question of the how well
  they are crafted

4
Well-crafted Architectures

• This session will focus on a set of techniques to
  maximize
• Communication
• Consistency
• Understandability
• Providing Context
• Documentation
• Instead of bickering in terms of how extensible
  or scalable, lets discuss how to craft a project
  to best describe an architecture

5
UML as

• Martin Fowler suggests UML is commonly used in
  three ways
• UMLAsSketch
• UMLAsBlueprint
• UMLAsProgrammingLanguage
• see www.martinfowler.com/bliki/

6
UMLAsSketch

• Typically on a whiteboard, in a drawing tool, on
  the back of a napkin
• Just enough design to get started writing code
• Probably used on every software project
• Disposable
• Lost learning opportunity perhaps

7
UMLAsBlueprint

• Model is a first-class element in the project
• Togethers sweet spot the model is the code, the
  code is the model
• Requires LiveSourceTM (simultaneous round-trip
  engineering)
• PSM (Platform Specific Model) in MDA (Model
  Driven Architecture)
• Key enabler to Model-Driven Development

8
UMLAsProgrammingLanguage

• Extensions to UML which provide the ability to
  model a system with sufficient specificity so as
  to be able to compile and deploy the application
  directly from the model
• Requires a UML profile, action semantics, model
  compiler
• Typically uses subset of UML class and state
  diagrams plus action semantics
• Some peoples view of MDA nirvana

9
Focus on UMLAsBlueprint

• UMLAsBlueprint approach provides the most value
  throughout the lifecycle
• Captures initial design
• Improves communication
• Stays in sync with evolution of project
• Always up-to-date documentation
• Useful in maintenance phases too
• Consider Alistair Cockburn
• Software development is a game whose two
  primary goals are to deliver the software and to
  create an advantageous position for the next
  game, which is either altering or replacing the
  system or creating a neighboring system Agile
  Software Development, Addison-Wesley, 2001.

10
Architecture Blueprints
11
Consistency

• Architectural blueprints are efficient because
  they use a common notational system
• UML provides a standard notation for software
• Blueprints are also effective because they are
  consistent

12
Coding Standards

• Every project defines its coding standards
• spaces vs tabs
• location of the curly braces
• naming conventions
• etc.
• Note Together includes Audits which automate
  inspection of source code to ensure projects
  adhere to coding standards

13
Modeling Standards

• Why dont more projects define similar standards
  for their UML models?
• Consider Scott Amblers UML Style Guide as a
  place to start http//www.agilemodeling.com/style
  /
• Note Together will soon include Model Audits
  which automate inspection of models to ensure
  projects adhere to modeling standards

14
Key Modeling Standards

• Legend (UML Note) to set context
• Inheritance horizontal or vertical
• Activity Diagrams flow horizontal or vertical
• Naming conventions
• Use Case template where does the use case text
  go anyway?
• Many more

15
UML Note as Legend
16
Inheritance Layout
17
Activity Diagram Vertical Layout
18
Activity Diagram - Horizontal Layout
19
Naming Conventions

• Same a Coding Standards
• Classes
• Singular, self-documenting
• Interfaces
• I prefix or able suffix
• Do you use ILog or Loggable?
• Package naming conventions
• Lowercase, no spaces
• Other modeling elements?
• Use Cases, Activities, States, etc.

20
Architecture Blueprints
21
Multiple Perspectives

• Sample blueprint only provided one perspective
• What about the carpenters? electricians?
  plumbers? the guy who purchases all the
  materials?
• Each one of these roles may require a completely
  different view of the project

22
Multiple Perspectives

• Software architectures require multiple
  perspectives as well
• Projects roles such as sponsors, architects,
  developers, testers, etc. all benefit from
  separation of concerns

23
Providing Context

• An Overview diagram is an easy way to guide
  various model viewers through the collection of
  diagrams
• Consists of UML Notes with commentary and a
  collection of shortcuts into the key sections of
  the model

24
Overview Diagram

• shortcuts

25
Separating Concerns

• Model partitioning
• separate projects vs packages in one project
• Providing views, multiple perspectives
• Reduce complexity
• don't have to absorb it all at once

26
Configuring Diagram Detail

• Diagrams can be configured to several levels of
  detail
• Analysis no types, no visibility
• Design add types and visibility
• Implementation show everything

27
Analysis Package

• Configure diagram to elide low-level details
• High-level detail which models the collaborations
• Analysis Object Model

28
Sample diagram Analysis
29
Sample diagram Design
30
Sample diagram Implementation
31
Hyperlinks Provide Traceability

• In Together, hyperlinks are a simple, yet
  effective, way to provide traceability within the
  model

32
UML Traces

• UML notation for traceability is an arrow with a
  dashed line and stereotyped as ltlttracegtgt
• This is often implemented as a line drawn on a
  diagram
• This is a flawed concept because
• traceability is a one-to-many relationship
• traceability should show relation of high-level
  to more refined view which means elements will
  not appear on the same diagram
• doesnt scale graphically trace links cause
  visual clutter

ltlttracegtgt
33
Model Traceability
Analysis
Design

• link analysis element to refinement

Hyperlinks as traces
34
Hyperlink Example
35
Intramodel Traceability

• For example

36
Architecture and LiveSourceTM

• Balancing preserving the design and the benefits
  of LiveSource
• Two diametrically opposed goals
• preserve the original design and
• living view of the app
• Guttenburg Dilemma (lose the thinking steps along
  the way)

37
Package vs Class Diagrams

• ltfour squaregt vs ltthree squaregt
• Fundamental concept you need to know
• Highly effective communication device

38
Package Diagrams

• Default view of a directory
• Shows all source files
• Classes and interfaces added externally
  automatically appear

39
Package Diagram Example
40
Class Diagrams

• Logical view
• Shows only elements added as shortcuts
• Useful for overviews, illustrating key
  architectural structures, temporary work diagrams
  and, of course, documentation

41
Class Diagram Example
42
Class Diagram Usage Scenarios

• Commonly used for
• Overview diagrams
• Logical views
• Illustrate key concepts within the model
• Automate dependency checking
• Temporary work product

43
Versioning Package and Class Diagrams

• Another project standard to consider
• Whether to version package diagrams?
• If theyre a default view of a directory, whats
  the point in putting them under version control?

44
Dependency Checking

• Right-click dependency
• and choose
• Show Dependencies

45
Documenting Component Usage
46
Documenting Pattern Usage
47
Modeling a User Interface
48
SWT Example
49
Questions and Answers
Tom Gullion Borland Software Corporation lttom.gull
ion_at_borland.comgt