Title: Documenting and Designing Architectures Using Together
1Documenting and Designing Architectures Using
Together
Tom Gullion lttom.gullion_at_borland.comgt
2Communication
- 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.
3Good 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
4Well-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
5UML as
- Martin Fowler suggests UML is commonly used in
three ways - UMLAsSketch
- UMLAsBlueprint
- UMLAsProgrammingLanguage
- see www.martinfowler.com/bliki/
6UMLAsSketch
- 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
7UMLAsBlueprint
- 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
8UMLAsProgrammingLanguage
- 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
9Focus 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.
10Architecture Blueprints
11Consistency
- 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
12Coding 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
13Modeling 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
14Key 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
15UML Note as Legend
16Inheritance Layout
17Activity Diagram Vertical Layout
18Activity Diagram - Horizontal Layout
19Naming 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.
20Architecture Blueprints
21Multiple 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
22Multiple Perspectives
- Software architectures require multiple
perspectives as well - Projects roles such as sponsors, architects,
developers, testers, etc. all benefit from
separation of concerns
23Providing 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
24Overview Diagram
25Separating 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
26Configuring Diagram Detail
- Diagrams can be configured to several levels of
detail - Analysis no types, no visibility
- Design add types and visibility
- Implementation show everything
27Analysis Package
- Configure diagram to elide low-level details
- High-level detail which models the collaborations
- Analysis Object Model
28Sample diagram Analysis
29Sample diagram Design
30Sample diagram Implementation
31Hyperlinks Provide Traceability
- In Together, hyperlinks are a simple, yet
effective, way to provide traceability within the
model
32UML 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
33Model Traceability
Analysis
Design
- link analysis element to refinement
Hyperlinks as traces
34Hyperlink Example
35Intramodel Traceability
36Architecture 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)
37Package vs Class Diagrams
- ltfour squaregt vs ltthree squaregt
- Fundamental concept you need to know
- Highly effective communication device
38Package Diagrams
- Default view of a directory
- Shows all source files
- Classes and interfaces added externally
automatically appear
39Package Diagram Example
40Class Diagrams
- Logical view
- Shows only elements added as shortcuts
- Useful for overviews, illustrating key
architectural structures, temporary work diagrams
and, of course, documentation
41Class Diagram Example
42Class Diagram Usage Scenarios
- Commonly used for
- Overview diagrams
- Logical views
- Illustrate key concepts within the model
- Automate dependency checking
- Temporary work product
43Versioning 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?
44Dependency Checking
- Right-click dependency
- and choose
- Show Dependencies
45Documenting Component Usage
46Documenting Pattern Usage
47Modeling a User Interface
48SWT Example
49Questions and Answers
Tom Gullion Borland Software Corporation lttom.gull
ion_at_borland.comgt