Upload
primrose-richardson
View
220
Download
1
Tags:
Embed Size (px)
Citation preview
1
Documenting the Architecture
CSSE 477 Software ArchitectureSteve Chenoweth, Rose-Hulman InstituteMonday, September 26, 2011
Left – architecture of the “Package2 TTCN-3 test platform,” one part of Go4IT, a project that provides “conformance to standards” IPv6 test tools and services. Figure shows the software interacting with users. From http://www.go4-it.org/modules/mediawiki/index.php/Technical_Documentation:_General_Design_Document.
Daily Quiz Q1 & 2
2
Today How to do the arch doc – this Short review of a couple short topics:
HW 3 Questions 5 & 7 – See last 2 slides Friday’s quiz, Q 4 (on customers), and 6 (on
parameters) – Slide before that In class today, brainstorm the changes to
make, with your “implementers”
3
Tonight Do Peer Eval on Angel, if you haven’t yet Project 3 –
In class today, brainstorm the changes to make, with your “implementers”
Tonight, 11:55 PM – Define the two sets of changes Wednesday, 11:55 PM – Turn in results of “timed
changes” – making the changes in your first set, before trying to improve on modifiability of your system.
This will be a journal entry describing your activities, and a spreadsheet showing each change, what module it was a part of or other relevant details, and how long it took. Then, of course, there’s a total time at the bottom.
Turn this in with tomorrow’s stuff – see next slide
4
Tomorrow Project 3 –In class, you’ll have a chance to explain how you’ll
improve modifiability, to your new group of “implementers”. Use them as consultants, to get feedback on the tactics you think will work. Start with Bass’s list of tactics (next-to-last slide from Modifiability ppt).
Try to figure out exactly what’s suitable for your needs. The turn-in for Fri night is to add to your journal what you and your implementers discussed, and what you’re going to try.
Then, of course, try to make the changes in the next couple days – not the second set of feature changes – just the “modifiability” changes. This should be a refactoring of your system, in the sense that the functionality of the system doesn’t really change. At the same time, you should be working on the first draft of your architecture document – one that includes at least what’s due Thursday…
Biweekly Quiz # 2 Similar to # 1, but over material we studied in after Quiz # 1. You’ll have more time. Will be 11 questions, need to get 10.
5
Coming Up See schedule – E.g.,
Thursday – HW 4Friday – First Arch doc draftMonday – Term paper topic!
6
The Arch Doc – References
Some of the material in these slides is taken from Software Architecture in Practice, 2nd edition by Bass, Clements and Kazman. Ch. 9.
A larger treatment of this same subject, by the same people is in: Documenting Software Architectures: Views and Beyond, by Clements, et al.,Now in a 2nd edition!
7
Outline
Stakeholder needs and views Arch document template Views – How to do the 3 kinds
Interfaces are a special concern A couple examples from prior classes
8
Different Needs of Stakeholders
Different stakeholder groups have different needsConsider the image on Slide 1 – who for?
Should provide different views to satisfy those needs In Project 4, we’ll add a client review!
Often create one document with different roadmaps for different groups
9
Stakeholdersand Views
10
First Cartoon of the Day
So,
11
Your arch doc target is…
What do the stakeholders really need / expect in order for:Them to participate as expected?,The project to succeed?, andYou to keep it up to date!?
You try to write only “that much.” So,
Above image of balancing act from www.joe-ks.com/archives_jul2006/BalancedFood.htm .
12
What’s the documentation template look like?Let’s look at the template, under handouts:
1. Introduction2. Background3. Functional
Requirements4. Quality Attributes5. Patterns and Tactics
6. Views Start here!7. Framework8. Acknowledgements9. References10. Revision history11. Appendices
13
Part 6: What views do you need for your project?
Project 3 asks for one of each:
Module (e.g., UML-ish, showing parentage and “uses”). See UML class diagram link.
Components and Connectors (pick an architectural style, show how it works as the system is running). Ref SEI article, next slide
Allocation (Deployment recommended – how it will look running and in-use). See slide 13 And document interfaces where needed (see slides 18+)
22
Map of our focus, within the whole arch doc
Doc has 11 parts –…Part 6 – Views…
(see slide 10)
3 kinds of views –
ModuleComponent & connectorAllocation
(see slide 11)
Each view has 7 sections –
1. Primary presentation.2. Element catalog
A. ElementsB. RelationsC. InterfacesD. Behavior
3. Context diagram4. Variability guide5. Arch background6. Glossary of terms7. Other info
2.C. Interfaces have 9 areas –…2. Resources provided…7. Element requirements…
}
14
Typical component & connector view From SEI article:
15
“Typical” deployment view You don’t have to get
fancy showing the people or equipment associated with the software.
Just get the point across about the relationship between the physical reality and the software.
Zillions of other examples on the web. Google images –
“deployment view”
From http://www.soi.wide.ad.jp/class/20050029/slides/14/44.html.
16
And what goes into each View?
According to Bass’s “template” for views, each view should/could have:
1. Primary presentation (the picture) – elements and their relationships
2. Element catalog – explains the picture
Note: Beyond this point, optional content, if you want the “view” and associated comments to be stand-alone vs referred to elsewhere:
3. Context diagram -- how the system relates to its environment4. Variability guide – how to exercise any variation points5. Architecture background – why the design reflected in the view came to be6. Glossary of terms used7. Other information
22
Map of our focus, within the whole arch doc
Doc has 11 parts –…Part 6 – Views…
(see slide 10)
3 kinds of views –
ModuleComponent & connectorAllocation
(see slide 11)
Each view has 7 sections –
1. Primary presentation.2. Element catalog
A. ElementsB. RelationsC. InterfacesD. Behavior
3. Context diagram4. Variability guide5. Arch background6. Glossary of terms7. Other info
2.C. Interfaces have 9 areas –…2. Resources provided…7. Element requirements…
}
17
Deciding how much of this you need…
Ok, you need the picture (Section 1)
And the basic explanation (Section 2) But even that has A – D!
In theory, for each view you could have all 7 sections of this associated info
Best to use a process of elimination – What don’t you need, or
is shown elsewhere?
Lots to do here -- See Slide 18
18
Second Cartoon of the Day
So,
19
Decide what’s really needed for each view Do sec 1-2, and Pick from 3-7 on Slide 14 as-needed If you eliminate those, then probably you need to
cover that territory in sec 5 or 7 of the arch doc format, in a common discussion about the views.
A common glossary could go in the Appendices. Remember this is the “high level design,” which
may need another layer before people get to coding.
20
Special concern: Documenting Interfaces
Included in Part 6 on Views Aspect “C” of Sec 2,
for some one of these views
Pictures of interfaces often look like component & connector views – the Fig on slide 14.
List of things to include with an Interface can vary…
22
Map of our focus, within the whole arch doc
Doc has 11 parts –…Part 6 – Views…
(see slide 10)
3 kinds of views –
ModuleComponent & connectorAllocation
(see slide 11)
Each view has 7 sections –
1. Primary presentation.2. Element catalog
A. ElementsB. RelationsC. InterfacesD. Behavior
3. Context diagram4. Variability guide5. Arch background6. Glossary of terms7. Other info
2.C. Interfaces have 9 areas –…2. Resources provided…7. Element requirements…
}
21
Documenting Interfaces, cntd – 9 areas to explain (focus on 2 of these)
1. Interface identity - unique name
2. Resources provided
3. Locally defined data types - if used
4. Exception definitions - including handling
5. Variability provided - for product lines
6. Quality attribute characteristics - what is provided?
7. Element requirements
8. Rationale and design issues - why these choices
9. Usage guide - protocols
22
Documenting Interfaces, cntd 2. Resources Provided Syntax - signature Semantics
assignment of values to data changes in state events signaled or messages sent how other resources will behave differently in future humanly observable results
Usage restrictions
23
Documenting Interfaces, cntd 7. Element Requirements
Specific, named resources Assumptions
Daily Quiz Q4
24
Map of our focus, within the whole arch doc
Doc has 11 parts –…Part 6 – Views…
(see slide 10)
3 kinds of views –
ModuleComponent & connectorAllocation
(see slide 11)
Each view has 7 sections –
1. Primary presentation.2. Element catalog
A. ElementsB. RelationsC. InterfacesD. Behavior
3. Context diagram4. Variability guide5. Arch background6. Glossary of terms7. Other info
2.C. Interfaces have 9 areas –…2. Resources provided…7. Element requirements…
}
Daily Quiz Q3
A couple examples
From last year’s class: On course website under Handouts –
SampleFirstArchDocs.
25
26
Friday’s quiz, Q 3, 4, 6 - Analysis
Q 4 was about customers and making changes - Employs the cardinal rules of extreme programming –Don’t add anything unless you are sure a customer will want it, except for -Refactor often, and always based on larger design principles
Q6 was about parameters in MS-OfficeWare.Parameters generally are a good way to “leave some of the programming for non-programmers” –
Your own installation people Customers picking options
Question – How far do you go down this path, as you architect how it’ll be built? Depends on how much “customization” is needed Adding parameters also prevents having to write different versions of code, and supporting
them But, what are the disadvantages?
27
HW 3 Question 5 - Analysis
The Q: “In the first lesson on architectural styles, we said that call and return designs discourage both recursion and multitasking, so as to keep it clear what “the thread of execution” is, and thus simplify both design and debugging. Ok, so which of the other styles would lend itself to both recursion and multitasking, and why?” Some answers: Multitasking – Good answers included: Distributed, blackboard, indirect, and others that promote more indirect coupling of processes. Also the “structural” form described in the Ch 8 case study, for real-time.Recursion – The real question here is more like, “Which designs don’t care so much about timely delivery of steps in a computation?” This is kind of a function of the system’s use, more than anything else. However, distributed, blackboard and indirect, for example, also leave options of getting something done via some other source.Real-time issues: Bringing the “structural” model of real-time systems into the picture brings up the question – How do you cut off a process elegantly? E.g., your chess AI needs to deliver a move in 2 minutes, but you’d like to let it continue searching for better moves, right up to that deadline. How do you do that?
28
HW 3 Question 7 - Analysis The Q: “Everyone would love a
system that could schedule classes for Rose students in a smarter way! Draw a picture showing what such a system would look like, as a blackboard (repository) design. Then explain how the “central repository” would be set up, what the independent computational elements would contribute, and what the inputs and outputs of the whole thing would be.”
Picture: Most of you showed, correctly, a blackboard in the middle with lots of sources of info, like about the student, courses, etc., adding to that.
The blackboard itself: Most importantly, this also should show the thing being built, the schedule of all this, with some entry and exit path for the whole activity.
Sample (pretty good)