6.031 — Software Construction
Fall 2017

Project: Flingball (Phase 2)

Team contract due
Wed Nov 29, 10pm
Milestone due
Wed Dec 6, 11am
Specs due
Fri Dec 8, 10pm
Project deadline
Wed Dec 13, 11am
Reflection deadline
Wed Dec 13, 11am

This is phase 2 of the Flingball pinball game system. Recall that in phase 1 you built a simulator that could represent balls, bumpers, and absorbers, and display the simulation in a graphical window.

In phase 2, you will add flippers, and the ability for the user trigger flippers and absorbers with the keyboard. You will also add network support, with the ability for boards to be connected across the network and exchange balls with each other through adjoining walls or teleporting holes (called portals).

The purpose of phase 2 is to help you gain more experience with:

  • Working with client-server networking
  • Working with threads and concurrency in a substantial program
  • Understanding and reusing code that other people have written (i.e., what makes code easy to understand?)
  • Adding new features and adapting to changed requirements (i.e., what makes code ready for change?)
  • Working in a small group with software engineering techniques like version control, specifications, and unit testing

Design Freedom

On this project, you have complete design freedom to choose the packages, interfaces, classes, and method signatures you use in your code. Choose them wisely; your design decisions will be part of your grade. You will be expected to use specs, tests, abstraction functions, rep invariants, safety arguments, checkRep and other assertions, and thread safety arguments.

The specification in this handout constrains what your solution must do, but you will have many design questions that are not answered in this handout. You are free to come up with your own answers to these questions – just be reasonable, consistent, safe from bugs, easy to understand, and ready for change. You can always ask your TA mentor or on Piazza for advice, but there is unlikely to be a single hard-and-fast answer.

On this project, Didit will run only your own tests. As always, correctness is your responsibility, and you must rely on your own careful specification, testing, and implementation to achieve it.

Your team’s repository

To get started, (note: only available after the project announcement in class)

  1. One member of your team should ask Didit to create a remote projects/fb2 repository, which will create a single repository shared by all members of your team.
  2. Then all team members will be able to clone the repo from Athena using Git:

    git clone ssh://username@athena.dialup.mit.edu/mit/6.031/git/fa17/projects/fb2/username1-username2-username3.git fb2

    List usernames in alphabetical order.

Overview

During the project, class meetings will be partly or completely replaced by team work time. Your team is expected to meet and work together during these times.

Checking in

Your team will be assigned a TA mentor who will help you with your design and help you stay on track as you implement it. You are required to check in with your TA during every team work time class. At this check-in, each team member should describe:

  • what they have accomplished since the last check-in
  • what they plan to accomplish by the next check-in
  • what, if anything, is blocking their progress

Use the check-in to review how each person’s plans fit together and decide how to resolve blocking problems.

Working together

Other than reflections at the end of the project, all parts of the project should be committed to the repository you share. Each commit to the repository should have a useful commit message that describes what you changed.

Use the code review skills you’ve practiced on Caesar to review one another’s code during the project. Caesar won’t have your project code loaded into it, however, so you can use in-person discussion or email for these reviews.

You are also strongly encouraged to try pair programming, where two people collaborate on a single computer. Pair programming is a skill that requires practice. Be patient: expect that pairing will mean you write code more slowly, because it’s like code review in real time, but the results are more correct, more clear, and more changeable. You can find plenty of advice on the Internet for how to structure your pairing.

When multiple people contribute to a commit, mention them in the commit message. Your TA will be reviewing the Git log to see individual contributions.

Pull before you start working, commit and push frequently, and don’t break the build!

Tasks

  • Team contract. Before you begin, write and agree to a team contract.

  • Understand the problem. Read the project specification carefully.

  • Design. As in phase 1, you will need ADTs for boards, balls, and gadgets; a parser for board files; a simulator for the pinball physics; and an animation system that draws everything on the screen.

    In addition, you will need to write code to handle keyboard input; devise a wire protocol for passing balls across the network; design multithreaded client and server components that communicate using that protocol; and design your system for thread safety and argue for its safety.

    Your software design is perhaps the most important part of the project: a good design will make it simpler to implement and debug your system. Remember to write clear specifications for classes and methods; write data type definitions for your expression data types; define abstraction functions and rep invariants, and write toString and checkRep; and document rep exposure safety and thread safety.

  • Test. Test your entire system on the staff sample boards, which you will also find in your starting repo. Furthermore, create at least three additional board files as tests. These should show that your client is able to correctly parse and simulate the various gadgets that can appear on the board, with trigger relationships, and that multiple clients can exchange balls with each other. You should also have JUnit tests that test smaller components of your system, and your test cases should be developed in a principled way (e.g., input space partitioning) justified by a testing strategy described in a comment, as we’ve been doing all along.

  • Implement. Write implementation code so that your tests pass. Iterate on the design and tests as needed to make the system work.

  • Reflection. Individually, you will write a brief commentary saying what you learned from this project experience, answering the reflection questions. Your reflection may not exceed 300 words.

Dividing the work

Every team member must not only make a substantial contribution to the project, but every team member must make a concrete contribution to every major component of the project.

For example, you may not assign one team member who is solely responsible for the parser.

Contributions include writing specifications, writing testing strategy, writing tests, prototyping, writing internal docs, writing implementation code, fixing bugs, and giving code review feedback. Contributions you work on as a pair or a whole team are great, as long as everyone is involved. Tasks like running meetings, taking notes, and tracking bugs are important, but don’t count as contributions under this requirement.

You must also divide the work such that every team member makes several different kinds of contributions. For example, you may not assign one team member who is solely responsible for writing tests.

Here is one suggestion for how to break down the work for a 3-person group. Fill in the cells of this grid so that it is a Latin square, i.e. no person is mentioned more than once in each row or column:

Core ADTs

User Interface

Networking

Specs

Tests

Code

Automated testing

Didit will compile your project and run your tests every time you push.

The automated testing page describes how Didit finds your tests, what tests can and cannot do, and how to exclude tests from execution.

You are not required to run any of your tests on Didit, but your project must compile and have a green build on Didit in order to be graded. If it doesn’t build on Didit, your TA won’t be able to build it either.

Specification

The project specification describes how the Flingball system must work for this phase of the project.

Provided code

Keyboard handling. Example code for doing both animated drawing and keyboard handling in Java can be found in Smile.java.

Physics. As in phase 1, the starting code includes a physics library. Documentation for the physics package is found online.

Parsing. The starting code also includes the jar for ParserLib, which must be used for parsing the file format. Documentation for ParserLib is found online.

Reuse and Integration of Phase 1

You are now in a new group for phase 2, and each of your group members has a different phase 1 implementation of the project. So your first step is to review each other’s phase 1 projects, discuss the pros and cons of their design and coding, and decide how to integrate them.

Each member of your group must bring at least one significant contribution from phase 1 into the integrated implementation. You don’t need to have been the primary author of what you are bringing from phase 1, but you must certainly understand it, be able to explain it to your teammates, and be able to integrate it with their contributions. Examples of significant contributions include:

  • ADTs representing boards, balls, and gadgets;
  • physics simulation code;
  • animated drawing code;
  • the grammar and parser for the board file format;
  • a substantial test suite for some part of the project

You may also choose to reimplement some or all of the phase 1 project from scratch. If you choose to reimplement it entirely, then each group member still has to bring a significant contribution from phase 1 in the form of design – e.g., a set of ADT operations, or a testing strategy.

You will have a meeting with your TA early in the project (see the timeline below). At this meeting, you will have to demonstrate that you have regained the phase 1 milestone in your new group – i.e., that your new group’s implementation satisfies the phase 1 requirements for running and displaying boards. Each of you will also explain what significant contribution you brought from phase 1.

Deliverables and grading

Wed Nov 29, 10pm
Your team contract must be committed to your group repository in a PDF file called team-contract.pdf in the top level of your repo.
Wed Dec 6, 11am
Milestone meeting: you will have a meeting with your group’s TA mentor, at which you will need to demonstrate: (a) a complete version of the phase 1 project, working and already committed to your repo, with each group member able to articulate what they brought from phase 1; and (b) some progress on specifications for phase 2 classes and methods, including a concurrency design (thread safety arguments for your console UI, networking code, and GUI). You will demo the code and discuss your work at the meeting. Have a laptop with the program ready to run.
Fri Dec 8, 10pm
You should have committed (1) specs for all your phase 2 classes and methods, and (2) some progress on testing and implementation.
Wed Dec 13, 11am
Project deadline. Your specifications, tests, and implementation should be complete and committed to your group’s repository.
Wed Dec 13, 11am
Reflection deadline. Individually, you should write a brief reflection and submit it using the reflection form. Your reflection should be at most 300 words of plain text.

Grades will be determined according to the following breakdown:

  • Team contract: 5%
  • Design: 25%
  • Implementation: 40%
  • Testing: 25%
  • Reflection: 5%

The milestone and specifications deadlines are graded as binary checkoffs. Missing each of these intermediate deadlines will cost 5 points on the overall project grade.

Check-ins with your TA mentor are also graded as binary checkoffs, either passed or missed. Missing a check-in costs 1 point on the overall project grade. You should check in with your mentor during class on:

  • Wed Nov 29
  • Wed Dec 6 (this is the milestone meeting)
  • Fri Dec 8
  • Mon Dec 11

Additional pages referenced above

Specification

Automated testing

Team contract

Reflection