Design Project R1 Guidelines

Introduction

This design project will have two releases. The teams will remain unchanged for both releases. The emphasis for the project is creating a software system design that considers general design principles such as coupling, cohesion, encapsulation, separation of concerns, maintainability, extensibility, and the Law of Demeter. Within the design, you should pay particular attention to the appropriate application of design patterns.

There are no "right" and "wrong" designs. There are "better" and "worse" designs which must be evaluated in the context of not only general design principles, but also the current application's context and requirements. An important aspect of your design discussion is the rationale and justification for your design choices and use of design patterns.

To get a good grade, the team must create a working program.  Since the emphasis of the course is design, spiffy implementations sitting on top of a weak design will not be viewed favorably.  This is also not a pattern frenzy: There will almost certainly be areas where it is not appropriate to apply a design pattern. However, a primary objective of this course are to gain experience designing patterns into a software system and implementing that design. As long as the intention of a design pattern justifies its use, err on the side of using the pattern even if that seems to make the design more complex than needed. For these relatively simple applications, it often will be "simpler" not to use a pattern, but given the objective above, do not use simplicity in and of itself as an excuse not to apply a pattern.

Each release will have a set of requirements defined.  The R2 requirements may necessitate refactoring of your R1 code base.  As you are introduced to new design patterns in class, read about them in depth in the Design Patterns book, and carefully consider whether or not to incorporate them into your design.

The two releases of the design project require an implementation of the design that you create.  The source code should include class and method/function headers.  The definition of the method/function signatures will be complete, i.e. include method name, data type and description of parameters, data type and description of return values.  In Java, this will be done using Javadoc tags; for other languages, the conventions used for that language (e.g., RDoc in Ruby) will be adhered to.

Submission Instructions

For submission of your R1 material, the team will place a zip file in the Design Project - R1 dropbox for in myCourses. Your file must be named XXrel1project.zip where XX is your two-digit team number. For example, if your team is Team 3, you will name your file 03rel1project.zip. Note that you can submit many versions of this file and they will all be kept in the dropbox, though your instructor will only look at the last submission.

Your XXrel1project.zip file should be clean of any version control system or other artifacts. This means no .git subdirectories; no extraneous files used by your IDE; just the files that are asked for below.

The XXrel1project.zip file must contain the following:

1. The final design documentation as a single PDF document. named design.pdf. Instructors may, at their discretion, further restrict the acceptable formats. This is the only file that the instructor will look at to evaluate your design.
   
   
2. A copy of the final presentation, named presentation.pdf. As with the design document, your instructor is free to further restrict acceptable forms of this document.
   
   
3. The code for your project including:
   
   
   1. Copies of the source files in a src, or other obviously named, directory.
      
      
   2. An executable file (if appropriate to the implementation language that you use; e.g., a .exe file for C or a .jar file for Java). Package your program so that it executes from a Windows Command Prompt window, i.e. outside of an IDE. The instructor will not use an IDE to run your program.
      
      
   3. A start.bat file to set any required environment variables, perform any program specific initialization, and execute your program. Your instructor will run this batch file as part of assessing your program's run-time behavior and quality.
      
      
4. A file README.txt with any other information (e.g., file locations, functional limitations) the team wishes the instructor to know.

Be sure to submit the XXrel1project.zip file before the deadline shown on the Design Project R1 drop box in myCourses. Late submissions will not be accepted; teams are advised to submit something early to ensure they receive at least some credit. Waiting until the last minute to submit something is a recipe for disaster. Each team member is individually responsible for ensuring the project is submitted on time, even if one team member is tasked with doing the submission.

Documentation Instructions

Your design documentation must include at a minimum the information below. This ordering below is not a linear ordering of information in your design document, but rather an itemization of the information that it must contain. You can use this template for the design document as a guide for your design documentation and the ordering of information. Each team may adjust that template if the team believes it would provide a better description of your project's design as long as the design document continues to contain all of the information listed here.

1. A title page, including the name of your team, the name of the project, the submission date, and the names all team members. The remaining information will start on the second page.
   
   
2. A narrative discussing your design:
   
   
   1. Describe your high-level architectural, i.e. subsystem, design.
      
      
   2. Give a rationale for the major design choices that you made.
      
      
   3. Tie back to specific requirements statements to show how the design covers the requirements.
      
      
   4. Outline how the design reflects a balance among competing design principles such as low coupling, high cohesion, separation of concerns, information hiding, the Law of Demeter, extensibility, reusability, etc.

   Include the UML domain model, UML class diagrams, CRC descriptions, UML sequence charts, etc., described below as part of the narrative; that is, these remaining elements should not be free standing. They support the reader as he or she works through your narrative. Also, consider organizing the narrative by breaking it down along major subsystem boundaries.

3. A domain model for your system that contains nodes for each domain entity and possibly entity attributes but no behaviors (aka methods). Make sure to include appropriate relationships with multiplicity indicators, inheritance relationships (if any) that you can discern from the problem description. The relationships should be labeled with tags that explain the relationship in the domain context.
   
   
4. A set of UML class diagrams
   
   
   1. Show the main classes and interfaces in your design, along with inheritance (generalization), association, aggregation, and composition relationships.
      
      
   2. Include multiplicity and role indicators as you deem appropriate to make the diagrams clear but not cluttered.
      
      
   3. Indicate pattern participation using stereotypes (i.e., in guillemets « and »).

   Rarely can you document your system, in a way that the reader can physically see and intelligently understand, using a single diagram. You will need several class diagrams at different levels of abstraction and for different subsystems to completely document your design. A top-level diagram may be just subsystems, or may be a mix of classes and subsystems. Next level diagrams would detail the subsystems.

5. The descriptions of the classes in your system using Class-Responsibilities-Collaborators "cards". Look at an example class description in CRC form. You can use the same CRC table template for your documentation.
   
   
6. A description of your pattern usage.
   
   
   1. Give each pattern a descriptive name within the context of the application, i.e. it is a Network State Observer and not just an Observer.
      
      
   2. Identify each class' role in the pattern. The class names themselves should reflect the class' contributions in the context of the application and must not be simply the class names from the pattern structure.
      
      
   3. Describe in the context of the application what each participant contributes, i.e. do not simply repeat the responsibilities of the class' participant in the pattern description.
      
      
   4. Describe the requirements of the system that the pattern is covering.

   This may be part of your narrative, or you may decide to present it separately possibly in table format. Here is an example of a description of a design pattern usage, and a template for the table used.

7. The sequence diagrams for at least two non-trivial features in the implementation. Check the problem statement for the features to diagram. If none are provided in the problem statement, then the team is to select the two features that provide the most insight into significant features of the system. Rarely will your sequence diagrams be able to stand alone. You will need to provide accompanying text to aid the reader in understanding the operation of the feature. It is strongly encouraged that you make this part of your narrative.
   
   
8. A discussion of the state of your implementation and any known issues with it.

Instructors expect a professional document that includes page numbers, section numbers and headings, and numbers for figures and tables.

Presentation and Demonstration Instructions

Some or all the teams will present their design to the class on the day the project is marked for completion. The presentation should include:

• a discussion of the design,
• how your design choices support the project requirements,
• identification of design pattern usage both in your own designed areas and any libraries being used,
• discussion of the difficulties encountered in creating the design,
• a critical assessment of the strengths and weaknesses of your design.

This is a formal presentation in that you should prepare it ahead of time and have visual material to support your presentation. All team members are expected to participate in the presentation. The team can decide on the approach to use. All team members must be present and be prepared to answer questions on the design. Your instructor will inform you in a prior class how long to plan your presentation.

Every student must be present for the presentations. Students on other teams listening to the presentations will need to pay close attention since individual students will be asked to provide feedback to the presenting team on positive and negative aspects of the design.

Some points to consider when preparing your presentation:

1. Make sure to use visual support to assist the audience in understanding your presentation. For describing your design, diagrams are very helpful.
2. It usually takes 2 to 3 minutes to cover the typical slide during a presentation. Use that as a guidline for your total number of slides when planning your presentation. A slide will go faster if it has minimal content.

Unless it is a very small class, demonstrations will typically be done on the next day of class. If time runs out, the instructor may need to set up a time outside of class to see the remaining demonstrations. Your instructor will let you know if all teams should be present for the entire demo class, or if teams should arrive at specific times.

Assessment

Note: You are not being graded on minute details of the functional behavior in your implementation.  Make sure that you cover the broad functionality and do not spend lots of time getting every small detail correct. You are graded primarily on quality of design and your implementation of it, how well you have achieved fitness for the purpose and your discussion of the rationale behind your design choices.

Rubrics

The instructor will use the following evaluation rubrics to grade each component of your project work:

• Design and Design Documentation Evaluation Rubric
• Presentation Evaluation Rubric
• The implementation rubric will be specific to R1 of your design project.

Here is some additional information describing areas typically needing improvement in designs.