Diagram review

1. Diagram review INF 123 – Software architecture tdebeauv@uci.edu

2. Outline • Reminders • Flowchart • State machine • Sequence diagram • Component diagram • Class diagram

3. Reminders

4. Reminder • Many diagrams can represent the same architecture • Diagrams represent design decisions • Diagrams don’t directly map to code • Code does not map directly to diagrams

5. Reminders • Crappy diagrams are easier to do than crappy code • Great diagrams are harder to do than great code • A diagram captures a design decision • It’s not easy! You need to think! Sometimes a lot! • Once you have taken a design decision, coding it is “only” a matter of technical proficiency • Coding = being able to speak French/English • Design decision = telling a good story

6. Reminder • Architects with different opinions • Level of detail • High-level view has components absent in a lower-level view • Static vs dynamic concerns • Component structure != protocol • Functional vs non-functional concerns • Broadcast the message to everyone vs scalability • Physical vs logical concerns • 2 self-contained subsystems for 3 machines

7. Example: level of detail (few details)

8. More details

9. Which of these 2 diagrams is correct? • Both! • Neither! • Depends on what you want to tell the stakeholders • Soft science, opinions, subjective, … • How do I grade this?

10. I grade (mostly) on style • Use the same symbol for the same things • Use standard symbols and representations • Don’t use the same symbol for different things • Add a legend if needed Client 1 Client 2 Send position Has a 2-way connection server

11. Reminder: Tools for diagrams • Dia https://wiki.gnome.org/Apps/Dia • Not just UML • ArgoUMLhttp://argouml.tigris.org/ • Eclipse UML plugins • Visio, PowerPoint, Word • Gliffy, Lucidchart, online tools …

12. Reminder: assignments • You are always welcome to submit a small text description along with your chart • I don’t require UML-compliant diagrams • But if you submit UML-compliant diagrams, mention it in your submission

13. Purpose of this review • For each type of diagram: • Minimum expectations • What makes a flowchart a flowchart • Do’s and don’ts • A reminder/introduction • Better grades!

14. Flowchart

15. Good: • Rectangles for actions • Diamonds for choices • Diamond arrows have labels • Dotted zoom-in explains in more details (could also be in another diagram if explicitly mentioned) • Dash-delimited area for actions in the same layer • Bad: • 2 start states • 2 end states • (should it be 2 different diagrams, though?) • No loopback after “drops packet” • More?

16. Good: • Colorful • Bad: • - Yes goes down, then Yes goes right (be consistent)

17. Good: • Legend • Green start, red end • Loopbacks everywhere • Meh: • Arrows can end into other arrows or into other boxes (be consistent) • Bad: • - “Assess compliance” == “Compliant?” (Maybe they mean that the assessment takes some time … then they should use a side note instead)

18. State machine

19. Good: • Transition labels are verbs (“Coin” should be “insert coin”) • States are participles (“locked”, “unlocked”) • States are circles • No end state: don’t need any in this case • Start state is obvious (nitpicking: convention is double circle)

20. Good: • Start state • End state is OK … • No crossing edges • Bad: • Low quality image • Start state not obvious • I don’t like coffee • Transition labels (“Espresso ON” should be “Turn Espresso ON”) • Tautologies (“Switch Off” to switch from “On” to “Off” …) http://msdn.microsoft.com/en-us/library/aa478972.aspx

21. Good: • Start state obvious • Colors are OK, but superfluous, unless they refer to other diagrams or a legend • Bad: • Verbs in states • Participles for transitions • Representing timers in state machines is difficult http://www.cs.cmu.edu/~dst/Tekkotsu/Tutorial/images/statemachine1.png

22. Good: • Arrow labels • Related states are nearby (StartMainTask.*) • Bad: • Low quality image • Too much • Transitions should be verbs • Bad: • Need a legend (why are some unblock in red and others in black?) • State duplication (detached, detaching) • Too close to the code (we want design decisions, not code visualization) • More?

23. Sequence diagram

24. Good: • Server lifeline starts at the same time as the computer’s • The server lifeline is active only when the server works • Dotted arrow for the response • OK/meh: • sendUnsentEmail has no arrow back: what is happening on the server? Maybe it does not matter … • Bad: • “response” label for the response

25. Good: • Booking lifeline created later • 2: should return the booking page URL • Bad: • No label on responses (why drawing the response then?)

26. Good: • Database symbol • Self-arrows (build SQL select) • Workflow easy to follow • Bad: • Hand-drawn • Hard to read • No lifeline (vertical dashed line all the time)

27. Component diagram

28. Good: • Provided lollipops on the left • Required lollipops on the right or down • Meh: • No need for <<component>> • No need for the rectangle symbol inside Order

29. Good: • Lollipops, with labels • Meh: • <<delegate>> arrows: just expose the interface to the outside • no need for squares

30. Good: • Two required interfaces join into one provided interface (Person) • Meh: • <<delegate>> arrows: just expose the interface to the outside

31. Class diagram

32. Good: • 0..* • Subscribes label • Meh: • +subscriber – what is it for?

33. Good: • Arrows for inheritance • Meh: • - I don’t care about attribute scope

34. Good: • Note “allows merchants …” • Meh: • Types (string, int) • Bad: • - No label on the arrows

35. Good: • Background color for packages (although: the diamond for Transaction -> Member should be white, not green) • Bad: • No label on the arrows (what is the relationship between Program and Member?) • id is not necessary (implementation detail)

36. Bonus: high-level diagram

37. Story Which architecture would you recommend for a patient-centered medical web portal? This portal would pull patient medical records from hospital databases. Patients often have multiple records (at least one per hospital they have ever been to). Hospitals allow an access to the records they hold, but only if the patients themselves request that access. Even if patients request for an access through the medical web portal, hospitals only grant a reading access (not a writing access). If the web portal stores medical records, it should comply with HIPAA regulations. The web portal also provides a calendar feature that reminds patients to do checkups, and tracks the doctor appointments of the patients for them. Patients may access the web portal through a web browser or an iPad app.