From lechner@cs.uml.edu Tue Dec 12 15:05:38 2006 From: Bob Lechner Subject: setgame06f/kbagley/models documentation - KB/RL replies To: kbagley@cs.uml.edu (Keith Bagley) Date: Tue, 12 Dec 2006 15:05:37 -0500 (EST) Cc: all RJLRef: $CASE/06f522/setgame06f/setgame06fDocumentationReview061211_kb_rl.txt Thanks for your prompt reply Keith. I added some clarifications at [RJL>... From kbagley@us.ibm.com Tue Dec 12 10:45:23 2006 > In-Reply-To: <200612120017.kBC0HuVV431715@venus.cs.uml.edu> > To: Bob Lechner > Cc: all > Subject: Re: review of setgame06f/kbagley/models documentation - FYInfo > > KB>> Responses below... > > Bob Lechner > 12/11/2006 07:17 PM > > To > alison_lea@yahoo.com, Keith Bagley/Bedford/IBM@IBMUS, cguffey@gmail.com, > agabriel@cs.uml.edu, nitin.sonawane@verizon.net, nsonawan@cs.uml.edu > (Nitin Sonawane), nitin.sonawane@gmail.com, lechner@cs.uml.edu (Bob > Lechner) > cc > > Subject > review of setgame06f/kbagley/models documentation - FYInfo > > > RJLRef: $CASE/06f522/setgame06f/setgame06fDocumentationReview061211.txt > > I have been reviewing Keith's web page re: setgame06f, at > http://www.cs.uml.edu/~lechner/06f522/06f522inCASE/kbagley/models/SetGame04_Website/content/_jaD1MH_REduGjo4XLZcPXw_root.html > > > I have no quarrel with his fine work, which documents analysis of > requirements and conceptual but not detailed design. > > UML CLass Diagrams are missing completely. Is this because this is not > Analysis level info? > > KB>>>> The UML class diagrams are there. You'll find them in the > appropriate "Overview" diagrams for each package/subsystem (e.g. Domain > Overview, Networking Overview, etc). For the C++ code, they are true class > diagrams with specifications of attributes (with typespecs) and > operations. For C code, I've encapsulated related functionality into > global pseudo classes for relations. For easy navigation to all the > diagrams, you can use the left-hand pane -- there's a section titled "All > Diagrams"; this helps navigate to the diagrams of interest, including the > class diagrams mentioned. > > > I do note the absence of some other design-level documentation below. > Sequence and/or collaboration diagrams from earlier (<= 04s) setgame > projects should be adapted as needed to document the design and > interaction aspects of setgame06f. > E.g., the UseCase Overview diagram needs expansions: one for Register and > one for Playgame. > > KB>>> The Playgame sequence diagram is there. Again, find it in the > diagrams navigation pane. I'd argue (and perhaps lose :-) that the > Register use case is trivial enough not to spend time doing an explicit > sequence diagram for it. I'm a believer in modeling for purpose, not for > the sake of modeling, if the diagram doesn't add value.....but that's just > me. > [RJL> I thought I discovered all Diagrams - one by one as the Diagram links appeared, scattered over the four Package rectangle links. But I never saw that one. In general, I find it hard to discover ANY layering inside the packages that would hide lower-level dependencies (<>). That's probably the tools' fault - perhaps they should make more use of 'make depend' output data or the equivalent. -------------------------------- > > Re: SetGame04::GUI::GUI Overview Diagram GUI Overview > > This has same problem as networking but is smaller so can print as one page. > Why are all boxes have paths called Assignment4c instead of setgame06f > project? > > KB>> My bad. When I started the reverse-engineering project, I called one > of the import packages Assignment4c. Again, for global C non-OO code > things have been imported and encapsulated -- the default name used was > the project name. I'll change that. > > That may be an artifact from setgame04s but these paths are obsolete? > Since there is no user interaction there are no Use Cases. > > KB>> A use case is a dialog between the system and Actors outside the > system, that returns a result of value to the Actor(s). Actors are not > necessarily People using a GUI. Actors can be other systems. Further, if > you use the notion of "use case flowdown", you can apply use cases to > subsystem interactions thereby implying that subsystems are Actors for > other subsystems. > > The GUI is self-contained subsystem of setgame. > I would like to know how it connects to the networking > use cases. This question has no visibiity whatsoever so far? > I suspect sequence/collaboration diagrams would clarify how and when > events cause GUI updates. > > KB>> Yes. That needs to be added > > ---------------------------- > > Re: SetGame04::Networking::Networking Overview - Diagram Networking > Overview > > Nice models - problem is, new MSExplorer 7 gives no way to > enlarge the right half of the picture - so it can print legibly. > > I gave up on getting IExplorer7, with its Vista label and unfamiliar > toolbar layout[, to select subareas not upper right corner, for printing]. > Its Print options cannot provide a printable inage of the > right half of this diagram. I can get the left half (portrait) and entire > drawing (landscape) but not the right half by itself, inside IE7 (or in > MSWord which imports a picture not its components). > > KB>>> Vista? Not much I can suggest here other than to drop Micro$oft. > Better yet, I'll put you in touch with one of IBM's lawyers, and you can > sue them for having goofy software :-) > > ----------------------- > > SetGame04::Use Case Model::UC Overview - Diagram UC Overview > > I do NOT see why the multiplicities are 1 to 1 on both player interactions? > although the description mentions "to each connected Player" > Perhaps >=2 players should be shown linked to Register and to PlayGame? > > KB>> That was a mistake (I forgot to turn off the tool option for UC > multiplicities -- I never use them and think they obfusgate what the > diagram is for anyway). I'll correct that. > [RJL> I agree with that (ignore multiplicity on Use Cases ) because it would be too unreliable (incomplete - defaults would be too narrow or too general). But they DO need to be somewhere (EERD/Class Diags). [conceptual] info models do NOT imply design specifics - until the design decision to e.g. make ad hoc structures or use a uniform implementation aproach like GEN/LCP. (For prototypes, you can expedt me to always make that decision in favor of uniformity - but I'm biased :-) [See someone's definition of a successful design (Ref?) - one that can be understood by others from its documentation - with a minimum of code-reading (especially for control flow, IMHO). Most UML models from commercial tools seem to me far too overloaded with details. These are ultimately necessary but belong at lower levels of the (call tree and control flow) hierarchy in order to make the design comprehensible. The hyperlinks from ovals to their hidden descriptive comments are very > welcome. > The Model Diagram Overviews need similar expansion to class content > because the big picture doesn't fit within a readable scroll window or > page otherwise. > > I DO like the comments re: > Use Case Model UseCase Play Game > Use-Case Specification: Play Game > > KB>> thanks > > > Where are network connection open/close conditions and activity? > (invisible to players but vital to server behavior). > No timing constraints are specified. > (what is required wrt. serialization of SeeASet events?) > > 3.1.1 BEGIN (PlayGame) > "The use case begins when the Player initiates a new Set game." > [This is not consistent with Register which says (rightly) a player must > register to get added to the list of players.?? > > > (The current Use Cases are not detailed enough to capture design constraints. > I am not saying they should, just that they are quite ineffective for a > DESIGN review. > Some critics say that Use Cases should not imply design decisions because > this pre-empts designer prerogatives. > > KB>>> Yes, and I am one of those people! :-) > [RJL> So am I. But I suspect we agree less on applying the same principle to conceptual data models - I say they do NOT constrain design but are necessary to disambiguate relevant real-world semantic relationships, including roles and multiplicities. At any rate, my focus in 522/OOAD is not requirements analysis but design (documentation and review). > That is true if they are early inputs to designers/implementers, but the > same Use Cases cannot be the only outputs from design.) > > KB>>> I'd argue that use cases are not design outputs at all. > Implementation, Platform Specific Models (PSMs), and executables are all > design outputs. Use Cases are a type of requirement that may be *refined* > during design, and are certainly an input, but to categorize them as a > design output is to use them inappropriately. > > The team should add these decisions to the Use Case descriptions > (qualified as Design constraints). Even more important: add (or reuse) > sequence diagrams/text to document EventMsg type flow and timing and > direction. > > NOTE: To preserve continuity with legacy code, prior (<=04s) sequence > diagrams (.ppt?) should be reused/revised to reflect current naming > conventions and protocols. That's part of the cost of refactoring legacy > code :-( > > KB>>> That sounds more like a good initial project for your 523 class; > definitely outside the "iron triangle" time and scope of assignment 4. [RJL> I believe Use Cases are appropriate as a checklist for Design Review topics, but ineffective at conveying design decisions - whose appropriateness should be the focus of Design Reviews. Use Cases are risky as a checklist if they are partial/incomplete. This has serious implications on legacy documentation - my main problem with setgame04s/04f/06f). Instead of Use Cases for only part of the requirements, we need more of them to complete the conceptual level, CIM constraint set. We also need class diagrams to show associative entities with multiplicities, and sequence diagrams to show networking between separate Client/player and Server/Controller processes. > Keith >