Software Engineering Project Report

Report #2: SYSTEM DESIGN -- Iteration 1(b) --  due dates for individual parts of this report are given here:
This report shall be submitted in three steps:
      1.   Part 1 (Section 1 Analysis and Domain Modeling)
      2.   Part 2 (Section 2 Interaction Diagrams and Section 3 Class Diagram)
      3.   Entire Report #2  (all sections included)

Note: Keep this report for future reference because it will be part of the final report (Report #3). Thus, as you progress through the semester, take every opportunity to revise, update and/or correct it.

While preparing this report, you may wish to check the grading checklist and avoid some typical mistakes in your report.

When submitting a part or the entire report, include the following sections and sub-sections. Each section/subsection should be clearly delineated with a proper heading.

• Cover Page and Individual Contributions Breakdown, as specified here.
  The contributions breakdown must contain the responsibility matrix and responsibility allocation chart as described in Report #1
• Table of Contents
  Make sure that the page numbers listed here are correct
• Work Assignment
  Show how you divided your team into 3 or 4 sub-teams and list the individual student competences

The report sections are as follows:

1. Analysis and Domain Modeling
   1. Conceptual Model
      Show the process of deriving the domain model and then draw the diagram. Provide text description of:
      1. Concept definitions
      2. Association definitions
      3. Attribute definitions
      4. Traceability matrix — show how your use cases map to your domain concepts.
   2. System Operation Contracts
      Should be provided only for the operations of the fully-dressed use cases elaborated in Section 3.c), for their system operations identified in Section 3.d).
   3. Data Model and Persistent Data Storage
      Does your system need to save data that need to outlive a single execution of the system?
      If NO, skip to the next item;
      If YES, identify the persistent objects and select the storage management strategy, e.g., flat files, relational database, etc.
      Attach the description of the file format and/or database schema (format of database tables, printed by the command description)
   4. Mathematical Model
      Do you use any mathematical models? E.g., you may use a statistical model for stock price prediction, or a geometric model for computing the trajectories for animate figures in a video game.
      If NO, skip to the next item;
      If YES, describe precisely your model.

• Project Management (described in Section 7 below) and References (described in Section 8 below)

2. Interaction Diagrams
   • Do interaction diagrams for the use cases you elaborated (“fully dressed”) in Report #1. You should do at least sequence diagrams, but you may do some other UML interaction diagrams, as well.
   • Describe what design principles you employ in the process of assigning responsibilities to objects. This can be done either as comment “bubbles” in the diagram, or in the caption of the diagram.
     Read the UML textbook about interaction diagrams and Section 2.5.1 in the course lecture notes, in order to learn about good design principles
   Here are examples of software tools for UML diagramming available for free download


3. Class Diagram and Interface Specification
   1. Class Diagram
      Show all classes and their associations. Only indicate visibilities of attributes and operations; full details about the types and signatures should be provided in the next item.
      If you cannot fit the class diagram on one page, or it looks too cluttered, create one “overview” class diagram showing all classes and their relationships, but for each class show only a single compartment with the class name (leave out attributes and operations).
      Then on subsequent pages show partial class diagrams, with three compartments and all the attributes and operations of a class. Make sure to indicate in diagrams and describe in text how partial diagrams fit into the overall class diagram.
   2. Data Types and Operation Signatures
      Independently of the class diagram, write down class specification in UML notation. For every class, specify data types of all attributes and operation signatures.
      Define the meaning of each class, operation, and attribute in plain language.
   3. Traceability Matrix
      Show how your classes evolved from your domain concepts. Provide explanations for modified names or multiple classes that evolved from a single concept—providing only a matrix with checkmarks is not enough!
      Note that if your system has many classes, the matrix may become difficult to read. Alternatively, you may list, line-by-line, all your domain concepts and explain which classes were derived from each concept and why.

• Project Management (described in Section 7 below) and References (described in Section 8 below)

4. Algorithms and Data Structures  (if applicable)
   1. Algorithms
      Describe the algorithms that implement mathematical models from your Report #1. Does your system use any other complex algorithms? For example, when computing a motion trajectory for an animate figure in a game, you may use some numerical or computer-graphics algorithms. Or, when assessing stock market movements, you may be using statistical algorithms.
      If NO, skip to the next item;
      If YES, describe your algorithms. For example, for the animate figure example above, will the path coordinates be precomputed and stored in a look-up table or will they be computed using a spline interpolation algorithm.
      It is a good idea to use activity diagrams to describe the algorithm design.
   2. Data Structures
      Does your system use any complex data structures, such as arrays, linked lists, hash tables, or trees?
      If NO, skip to the next item;
      If YES, what criteria you used in deciding what data structure to use, e.g., performance vs. flexibility?
   3. Concurrency: Does your system use multiple threads?
      If NO, skip to the next item;
      If YES, identify the objects that have separate threads of control and describe any synchronization between the threads?


5. User Interface Design and Implementation
   • Describe whether and how you modified and implemented the initial screen mock-ups developed for Report #1. Comment only on significant changes in your user interface, those that reduce (or increase) the user effort. Changes of colors or styles are less important and should be omitted from your report.
   • The textbook does not deal much with the GUI design. Excellent guidelines for GUI design can be found here:
     Sun Microsystems, Inc. Java Look and Feel Design Guidelines. Mountain View, CA, 1999. Available at: http://java.sun.com/products/jlf/ed2/book/
   • “Ease-of-use” is generally considered a key characteristic of user interface. “Ease-of-use” should not be confused with a flashy interface, with lots of colors, picture, graphics, etc. On the contrary, you should avoid flashy user interfaces. “Ease-of-use” means that interface is intuitive, easy to understand and operate, without having to ask many questions or read voluminous documentation. A minimal user interface that is well organized should be sufficient. You already considered the user effort as part of Report #1, and here you should strive to minimize the user effort, thus maximizing the “ease-of-use”.


6. Design of Tests
   Note that for this report you are just designing your tests; you will program and run those tests as part of work for your first demo, see the list here.
   1. List and describe the test cases that will be programmed and used for unit testing of your software.
   2. Discuss the test coverage of your tests.
   3. Describe your Integration Testing strategy and plans on how you will conduct it.
   Describe also your plans for testing any algorithms, non-functional requirements, or user interface requirements that you might have stated in your Report #1.


7. Project Management and Plan of Work
   1. Merging the Contributions from Individual Team Members
      Compiling the final copy of the report from everyone’s work, ensuring consistency, uniform formatting and appearance.
      Describe what issues were encountered and how they were tackled.
   2. Project Coordination and Progress Report
      What use cases have been implemented?
      What is already functional, what is currently being tackled?
      List and describe other relevant project management activities.
   3. Plan of Work
      List the projected milestones and dates by which you plan to accomplish them. Preferably, you should use Gantt charts for planning and scheduling your project.
   4. Breakdown of Responsibilities
      • List the names of modules and classes that each team member is currently responsible for developing, coding, and testing
      • Who will coordinate the integration?
      • Who will perform and integration testing? (The assumption is that the unit testing will be done for each unit by the student who developed that unit.)
8. References
   The list of references should contain exact references and URLs of any material that is used in the project and does not come from the textbook.

Section 1 Analysis and Domain Modeling must include the description of how the domain model was derived. It should show the analysis process that you carried out to derive your domain model. Showing only the domain model diagram will yield very few points.

NOTE: No matter what programming language you use to implement your software (Java, PHP, C#, Flash or something else), you must first provide generic, language-independent design diagrams (interaction diagrams) in UML.
Second, if you are implementing your software in a non-object-oriented language, you should additionally provide implementation-specific sequence diagrams for your software. In this case, please explain, step-by-step, how your implementation diagrams correspond to your generic UML design. This means that the classes and methods from the generic design must be traceable to the functions of your non-object-oriented implementation. See Chapter 2 in the textbook and Miles & Hamilton: Learning UML 2.0 for the how to create interaction diagrams.
Source code should not be submitted with this report, but rather should be included with your first demo materials.

NOTE: Comment your diagrams! Describe all design decisions and other things that are not obvious from the diagrams. Any useful information is welcome. There is no limit on the number of pages for the report. Having good comments and explanations greatly helps in reading and evaluating the project and will positively contribute to your grade.

Drawing Interaction Diagrams. Theoretically, a single interaction diagram should be drawn for each system function (check your system sequence diagram - SSD). Because some system functions are trivial, I suggest the following practical technique. Start drawing one interaction diagram per use case. If, at some point, the diagram overflows to the next page, split your interaction diagram and draw one diagram per system function.

Applying Design Principles. It is very critical to pay attention to the proper use of the design principles described in Section 2.5 of class lecture notes. (Quick refresher: design principles include: Expert Doer, High Cohesion, Low Coupling.) Proper responsibility assignment, separation of application logic from presentation and storage tiers is of the utmost importance and will be given a great weight in grading the reports. It is important to document the alternative solutions that were considered in the design process, identify all the tradeoffs encountered and explain why the alternatives were abandoned.
You should also check other design principles that were not covered in the class, such as SOLID (also see here)  and  GRASP.

The tests in Section 6 are preliminary designs that may be changed and refined when you will do actual testing for your first demo.
Note that you are not expected to write any program code for unit testing for this report. Test code writing and running the tests is expected for the first demo, see item #2 in this list.
For Report #2, you should just describe which classes/functions should be tested and how you would go about doing it. You need to derive the state diagrams and to draw the test case tables.
Also discuss the coverage of your unit tests. Recall that you are doing State-based testing, so your coverage should be analyzed in terms of states and transitions. A minimum acceptable strategy for responsible testing of a state diagram comprises testing these:

• Cover all identified states at least once (each state is part of at least one test case)
• Cover all valid transitions at least once
• Trigger all invalid transitions at least once

As you progress with presenting your UML diagrams, make it clear in the text what tools/platforms/languages you are using or will be using to implement your system. State where to find more information about the software tools/platforms/languages that you are using, and list the relevant links in the references (Section 8). Do not leave us wondering if even a serious detective work would be able to find out what exactly you used or are planning to use for your project.

The greatest problem is that Report #2 usually has is that it may appear to be created almost independently of your Report #1, without any reference to your Report #1. A key of good software engineering is to maintain logical progression among the artifacts (i.e., traceability): from requirements, through conceptual modeling, class deign, to code implementation.

This most often reflects in how your interaction diagrams evolved from your Report #1, i.e., from your system sequence diagrams and your domain model. Often, there is no clear connection! It is impossible to trace how classes/objects in your Report #2 evolved from the domain model in your Report #1. The diagrams in your Report #2 may seem to have been invented independently of all analysis that you did for report #1!! That renders your report #1 useless and that is a bad software engineering.

To do it properly, your Report #2 must do the following.

1. For each interaction diagram, it must be explicitly stated from which system sequence diagram it evolved and which system method it details.
2. In each interaction diagram, at least some of the concepts from your domain model must be used. Even if, while doing Report #2 (after Report #1 was submitted), you discovered that most of those concepts need to be modified or new concepts introduced, your Report #2 must explicitly state which new objects (in your interaction diagrams) evolved from the old concepts (shown in the domain model of Report #1, which you may revise and enclose when submitting Report #2). If you needed to introduce new objects (and there is nothing in your domain model in Report #1 that corresponds to these new objects), that is fine, but you must explain why these new objects are needed and explain in at least one sentence why they were not discovered during the domain analysis phase in Report #1.

A common excuse heard from students is that their software ended up being implemented using PHP, Flash, or some other non-object-oriented language, so there is no clear correspondence between classes and PHP scripts. This is not a valid point. Your implementation must be based on your conceptual analysis (otherwise your conceptual analysis is useless). Your implementation is just one way to implement your conceptual model, using the programming language of your choice. If you did good job in your conceptual analysis, then it should be possible for another developer to take your conceptual model and implement it in a different programming language. Therefore, you must be able to trace the origin of your PHP scripts (or whatever other program units) back to the concepts from your conceptual model. You must make this tracing explicit, instead of expecting the instructor to labor through your reports and try to figure out which PHP script originated from which abstract concept in your domain model.

As you gain better understanding of your problem or invent a better solution, you should make all necessary changes to your documentation. That is the point of iterative approach: we develop a system through repeated cycles (iterations) and take advantage of what was learned during development of earlier parts or versions of the system. Therefore, you are encouraged to make revisions and improvements to your past documentation (Report 1) as you learn more.

Updating the Materials From Report #1. Use case diagrams, domain model, and even the requirements from (Report #1) may need to be updated as you progress with your project development. This is normal on software projects and it is important that you update your first report to accurately reflect your current project status. If you made significant changes and it may be difficult to understand your Report #2 without seeing your revised first report, then you should provide us with your revised report, as well. It would be helpful if you provide a brief summary of changes somewhere in your updated report version, so we can better understand the evolution of your project.
We will not grade your revised report #1 nor provide feedback on it, but we will consult it when grading Report #2. We will grade your revised Report #1 when it will be submitted as part of Report #3.

2.   Report Preparation

The guidelines remain the same as for Report #1.

Here are some options for software tools for UML diagramming. You may search the Web and find some other tool as well. Any tool that supports the UML symbols is acceptable.

See also the grading policy for the assigning the overall team grade vs. grades for the individual members.

This report will be graded only after the entire report is submitted.
Individual parts of the report will not be graded immediately after the submission.
However, 50% of points will be deducted from the parts that were not submitted on time.
If time permits, we may provide feedback on the individual parts before the entire report is due.

All reports will be graded independently of each other, based on the grading checklist.
The maximum possible point score for each report is 100 points. The actual score may be lower, depending on the quality of different elements of each report.

Each team member will be assigned points, based on their declared contribution to the report, as detailed here.

4.   Report Submission

You may include your revised Report #1 with your Report #2, if you feel that you made significant changes and having your updated Report #1 can help us better understand your Report #2.
However, we will not grade the updated Report #1 and will not provide any feedback on the revisions. We will grade revised Report #1 when it will be submitted as part of Report #3.

When submitting Part 1, the document must include the following sections:

• Cover Page and Individual Contributions Breakdown
• Table of Contents
• Section 1:  Analysis and Domain Modeling
• Project Management
• References

When submitting Part 2, the document must include the following sections:

• Cover Page and Individual Contributions Breakdown
• Table of Contents
• Section 1:  Analysis and Domain Modeling — revised as needed
• Section 2:  Interaction Diagrams
• Section 3:  Class Diagram
• Project Management
• References

The full report must contain all sections specified in the Report Format  (previously submitted parts of this report may be revised as needed).

Each team should email their report (PDF document only!!!) both to the instructor and the TA on or before the due date.
The report should also be posted for download on your project website (for free web hosting, see here).

Submission deadline is usually by end of the day on the due date.