documenting and designing architectures using together tom gullion
TRANSCRIPT
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
