Project: Crossword Extravaganza
We tend to think of solving crossword puzzles as a solitary activity, but not anymore! For this project, you will be creating a venue for multiplayer collaborative crossword puzzle solving. Specifically, you will be constructing a system that will allow users to solve a crossword puzzle together, over the network.
The project will exercise many of the concepts you learned in class. You will implement a client/server architecture and develop your own wire protocol; you will use ParserLib to read in crossword puzzles, parse wire protocols, and parse a command-line user interface; and you will develop your own abstract datatypes to represent different aspects of the system. Most importantly, you will also practice working in a small group, using the software engineering techniques we have learned this semester.
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.
You will be expected to use specs, tests, abstraction functions, rep invariants, safety arguments, checkRep and other assertions.
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
One member of your team should ask Didit to create a remote
projects/crosswordrepository, which will create a single repository shared by all members of your team.Then all team members will be able to go to Didit, follow the link to your team repo page, and find the
ssh://URL at top. Clone and import into Eclipse.
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 be prepared to:
- say what they have accomplished since the last check-in
- say what they plan to accomplish by the next check-in
- say what, if anything, is blocking their progress
- show that their own working copy of the project is committed, pushed, and up to date with the remote repo
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, with one person watching over the other’s shoulder, or watching by videochat and screenshare. 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.
Note that “pair programming” normally means just one keyboard, with one person driving (typing) and the other person in the backseat (code reviewing). So you are editing only one working copy, and committing the changes just once. 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.
What we do in class with Constellation is a closer kind of collaboration than normal pair programming. Using Constellation during the project is possible but not encouraged, because it makes identical changes on two computers that require careful coordination to avoid merge conflicts. But if you really want to use Constellation, then before starting the collaboration, make sure both sides are in a clean state, with no uncommitted changes and fully in sync with the remote repo. After collaborating, both sides should commit the changes to their local repos, then push and pull until the commits are merged and both sides are again in a clean state. Note that you must be extremely disciplined to use Constellation and Git together successfully. Never walk away from a Constellation collaboration without cleaning up and getting merged.
Tasks
Team contract. Before you begin, write and agree to a team contract. This is due at the end of class on the day the project kicks off.
Understand the problem. Read the project specification carefully.
Design. You will need to create abstract datatypes for various parts of your system, both client and server, and a grammar for parsing puzzle file input.
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; define abstraction functions and rep invariants, and write
checkRep; and document safety from rep exposure.Note that you are required to use ParserLib for this project – at a minimum for reading puzzle files, and also for wire protocol (if your design uses network sockets) and user command processing (if your design has a textual user interface).
You will also need to document the specification of the wire protocol between your client and server, putting it in the file
src/crossword/client-server-protocol.txt.Iterate. Design the parts of the system required for the first iteration milestone, explained below. Test and implement them. Then revisit your design, improve the specifications, and test and implement more. And so on.
Test. You should write JUnit tests for the individual components of your system. Your test cases should be developed in a principled way, partitioning the spaces of inputs and outputs, and your testing strategy should be documented as we’ve been doing all along. Parts of your program may require manual testing, which you should document clearly described as in problem set 4.
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, and should be submitted to the reflection form.
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.
Use a Latin square, like the one below, to break down the work for a 3-person group so that it satisfies the constraints above. Fill in the cells of this grid so that no person is mentioned more than once in each row or column:
| Server | Game logic | Client UI | |
|---|---|---|---|
In this grid, the server includes all the code necessary to accept clients, manage collaborative play, and transmit updates to clients. The game logic includes all the rules of the game itself, including ADTs for puzzles, puzzle file loading, and logic to check puzzles for consistency. The client UI includes all the user interface code for interacting with players. This is one possible way to break down the work; your group may choose to do it differently, as a result of your design decisions.
Note that you may need to rebalance your work breakdown among group members as the design and implementation challenges become more clear, so be prepared to revisit this Latin square and change the rows or columns if necessary.
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 Crossword Extravaganza system must work.
Provided code
It’s fine to use any code provided in this semester’s class. For example:
If you choose to build a graphical user interface, we have also provided some example code as a starting point on how to set up a user interface and draw crossword puzzles in it.
This code is found in the src/crossword/gui directory in your Git repo.
We also provide some example crossword files that you can use to test your system.
These files are found in the puzzles directory in your Git repo.
This assignment asks you to implement a crossword puzzle system, so remember that it is not appropriate to reuse crossword-puzzle components from an external source.
First iteration
At the first-iteration milestone, you should demonstrate a server that reads one valid puzzle file, waits for a connection from a client, and when the client connects, communicates the puzzle (its grid and clues, but not answers) to the client, and the client then displays the puzzle in its user interface.
Note that the first iteration can omit puzzle-consistency checks, concurrency, and handling player actions. If sending and displaying a full puzzle grid is too much, then get the grid cells and clue for at least one word of the puzzle. The most important thing is that your first iteration must be end-to-end, with initial versions of all parts of the system (client, server, parser, ADTs, user interface), all connected together.
This is a first iteration, but you should still include a first draft of specs, tests, datatype definitions, rep invariants, abstraction functions, and equals/hashCode/toString defined where appropriate.
Remember that none of these things are final yet!
Your experience with the first iteration will help you revise and improve them.
If you are having trouble with the first iteration, seek help early!
Deliverables and grading
- Mon Nov 16, 12:30pm
- (end of class)
- Your team contract must be committed to your group repository in a PDF file called
team-contract.pdfin the top level of your repo. - Fri Nov 20, 11am
- First-iteration milestone meeting: you will have a meeting with your group’s TA mentor, at which you must demonstrate the deliverables described under first iteration.
You will demo the code and discuss your work at the meeting.
Have a laptop with the program ready to run.
Make sure to commit your code to your group’s repository before this meeting.
- Wed Dec 2, 11am
- Specs milestone meeting: by this meeting, you should have committed (1) a ParserLib grammar for puzzles (and another for your wire protocol and another for your text command language, if those components exist in your design); (2) a spec of your client/server wire protocol in
src/crossword/client-server-protocol.txt; (3) specs for all your classes and methods, as well as datatype definitions, AFs and RIs, and a concurrency design and thread safety arguments, in a design that addresses all the requirements of the Crossword Extravaganza specification; and (4) substantial progress on testing and implementation (relative to the first iteration). - Fri Dec 4, 11am
- Project deadline.
Your specifications, tests, and implementation should be complete and committed to your group’s repository by this deadline.
You will have a final meeting with your TA mentor during this day’s class, to demo and discuss your project.
- Fri Dec 4, 12:30pm
- (end of class)
- 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, and submitted by the end of this day’s class.
Grades will be determined according to the following breakdown:
The first-iteration and specifications deadlines are graded as binary checkoffs. Missing each of these intermediate deadlines will cost 5 points on the overall project grade. The associated milestone meetings also contribute to your design and implementation grades.
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: