1 Documenting the Architecture CSSE 477 Software Architecture Steve Chenoweth, Rose-Hulman Institute Monday, 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 it.org/modules/mediawiki/index.php/Technical_Doc umentation:_General_Design_Document. it.org/modules/mediawiki/index.php/Technical_Doc umentation:_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 4  Friday – First Arch doc draft  Monday – 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 2 nd 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 needs  Consider 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 Stakeholders and 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?, and  You to keep it up to date!? You try to write only “that much.” So, Above image of balancing act from

12 What’s the documentation template look like? Let’s look at the template, under handouts:template 1. Introduction 2. Background 3. Functional Requirements 4. Quality Attributes 5. Patterns and Tactics 6. Views  Start here! 7. Framework 8. Acknowledgements 9. References 10. Revision history 11. 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.UML class diagram Components and Connectors (pick an architectural style, show how it works as the system is running). Ref SEI article, next slide  SEI article Allocation (Deployment recommended – how it will look running and in-use). See slide 13   And document interfaces where needed (see slides 18+)

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

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 environment 4. Variability guide – how to exercise any variation points 5. Architecture background – why the design reflected in the view came to be 6. Glossary of terms used 7. Other information

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…

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 – Module Component & connector Allocation (see slide 11) Each view has 7 sections – 1.Primary presentation. 2.Element catalog A.Elements B.Relations C.Interfaces D.Behavior 3.Context diagram 4.Variability guide 5.Arch background 6.Glossary of terms 7.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)