documenting and designing architectures using together tom gullion

Documenting and Designing Architectures Using Together

Tom Gullion<tom.gullion@borland.com>

Communication

Architecture is all about communication.

Today’s 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.

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…

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, let’s discuss how to craft a project to best describe an architecture

UML as…

Martin Fowler suggests UML is commonly used in three ways:

• UMLAsSketch• UMLAsBlueprint• UMLAsProgrammingLanguage

see www.martinfowler.com/bliki/

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

UMLAsBlueprint

Model is a first-class element in the project

Together’s 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

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 people’s view of MDA nirvana

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.

Architecture = Blueprints

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

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…

Modeling Standards

Why don’t more projects define similar standards for their UML models?

Consider Scott Ambler’s 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…

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…

UML Note as Legend

Inheritance Layout

Activity Diagram – Vertical Layout

Activity Diagram - Horizontal Layout

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.

Architecture = Blueprints

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

Multiple Perspectives

Software architectures require multiple perspectives as well

Projects roles such as sponsors, architects, developers, testers, etc. all benefit from separation of concerns

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

Overview Diagram

shortcuts

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

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

Analysis Package

Configure diagram to elide low-level details

High-level detail which models the collaborations

Analysis Object Model

Sample diagram: Analysis

Sample diagram: Design

Sample diagram: Implementation

Hyperlinks Provide Traceability

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

UML TracesUML notation for traceability is an arrow with a

dashed line and stereotyped as <<trace>>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

– doesn’t scale graphically – trace links cause visual clutter

<<trace>>

Model Traceability

link analysis element to refinement

Design

Analysis

Hyperlinks as traces

Hyperlink Example

Intramodel Traceability

For example:

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)

Package vs Class Diagrams

<four square> vs <three square>

Fundamental concept you need to know

Highly effective communication device

Package Diagrams

Default view of a directory

Shows all source files

Classes and interfaces added externally automatically appear

Package Diagram Example

Class Diagrams

Logical view

Shows only elements added as shortcuts

Useful for overviews, illustrating key architectural structures, temporary work diagrams and, of course, documentation

Class Diagram Example

Class Diagram Usage Scenarios

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

Versioning Package and Class Diagrams

Another project standard to consider

Whether to version package diagrams?

If they’re a default view of a directory, what’s the point in putting them under version control?

Dependency Checking

Right-click dependency

and choose

“Show Dependencies”

Documenting Component Usage

Documenting Pattern Usage

Modeling a User Interface

SWT Example

Questions and Answers

Tom Gullion

Borland Software Corporation

<tom.gullion@borland.com>