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? I don't believe it. Attributes and relations with multiplcities are fully as definable for the conceptual info content, except that design could add or refine the inheritance aspects. That might go easier if essential semantic information about the game and its collaborators is captured and documented during analysis. So where are the [E]ERD/class models? 
I deplore the term <<uses>> for relation links on both GUI and networkOverview Domain Models, because it doesn't say how, nor does it show multiplicities which I would expect in a UML Class model. If EERD/Class (semantic info) models are done first, would <<uses>> become less ambiguous or not needed? I believe it wold help qualify the kind of <<use>> to help understand usage modes. 


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.
Perhaps there should also be a diagram for 'Exchange Messages'.
I also have some general complaint about tool graphics.

--------------------------------

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?
That may be an artifact from setgame04s but these paths are obsolete?
Since there is no user interaction there are no Use Cases. 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.

----------------------------

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.

Left half of this diagram seems to be about 06f/04s?  port/socket connections
but right half talks about DBDE packets and events. Not up to date for 06f.

I gave up on getting IExplorer7 with its Vista label and unfamiliar toolbar layout. 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).

-----------------------

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?

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
1. Brief Description
In this use case the system interacts with the Player[s?] to manage an ongoing game of Set
...

I note 
"a Set ... increases the Player's score by one point."   
(I prefer this, but it is 5 or 25  in ag's demo 12/5?
Is "PLAYERS CAPTURE SETS" different from "PLAYER CAPTURES SETS"? or a typo?


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.??

--------------------

Use Case Model 	UseCase Register  Use-Case Specification: Register

1. Brief Description/Comments:
"In this use case the system adds Players to the registry of active players for a game of Set" 

Neither Register nor PlayGame says HOW the player begins (or ends, or iterates) the action,
nor how Register constrains/enables PlayGame.

Conclusion: A very nice job of documenting the (which?) setgame system
at the analysis and preliminary design level.  I would prefer diagrams that fit on one page and remain readable. This probably requires hyperlinks to hidden content for Domain Model classes. 

Re: Use Cases: These, being analysis-level documents, still should not ignore concurrency and distribution requirements such as serialization of events to the server, and message type (EventType) (content and flow direction) specs.

UML (or COOL) supports such design decisions by collaboration/sequence/activity/state diagrams and EventType specs. 

(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. That is true if they are early inputs to designers/implementers, but the same Use Cases cannot be the only outputs from design.)

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 :-(

In conclusion, the current documentation hides many implementation concerns, and the Domain Model does not reflect server/client separation. I would like to explore how to document this aspect of distributed design on Tue Dec 12.

-----------------------------------------

Use Case Model 		UseCase Exchange Messages 
Exchange Messages is the mid-tier infrastructure use case for transmitting and receiving messages to/from the Client and Server
(A diagram could suggest collaboration and communication aspects?).

------------------------------------