# Project The goal of CS 3110 is to help students become excellent programmers who can design and implement software that is elegant, efficient, and correct, and whose code can be maintained and reused. Toward that end, a significant part of A5 and A6 will be devoted to a team programming project. You will form a team, choose a system you want to build, design it, review your design with a member of the course staff, implement the system, and submit it along with additional documentation. The constraints are few and the space is large. You'll need to make decisions and solve problems along the way. We hope you find it highly rewarding. Quick links to project milestones: * [Milestone 0 (Charter)](#ms0) * [Milestone 1 (Design)](#ms1) * [Milestone 2 (Implementation)](#ms2) ## Overview You will choose one of the following systems to build. Each system (except the last) has a short description. Each could be refined into an acceptable project, and you should feel free to do so. Or, if you prefer, you may opt for the last choice and invent your own system. Your system may not involve extending an assignment from this course or another course; it should be a fresh implementation effort. * **Game.** Create your own version of your favorite game and an AI to play it. The game might be two-player or multi-player. Humans would be able to compete against the AI. The complexity of the game should be comparable to or greater than [Battleship][battleship] or [Texas Hold'em poker][holdem]. * **Database.** Create a database management system (DBMS) that supports basic [SQL][sql] queries, including creating and dropping tables; inserting, updating, and deleting rows; and SELECT...FROM...WHERE queries. The database would be stored as a file that is updated throughout execution, so that it survives failures of the server. Your implementation would include a REPL that permits interaction with the DBMS. * **Editor.** Build a text editor similar to [nano][nano], though likely with a smaller feature set. Your editor would enable creating and changing files on disk. It would support find-and-replace of text. Use an [OCaml text interface][text] such as AnsiTerminal to implement the interface. * **???.** Build a system of your own choice. The scope of the system should be similar to those suggested above. [battleship]: https://en.wikipedia.org/wiki/Battleship_(game) [holdem]: https://en.wikipedia.org/wiki/Texas_hold_%27em [sql]: https://en.wikipedia.org/wiki/SQL [nano]: https://en.wikipedia.org/wiki/GNU_nano [text]: http://caml.inria.fr/cgi-bin/hump.en.cgi?sort=0&browse=64 *Non-requirements:* A graphical user interface is not required. Text-based interfaces will suffice. Similarly, a client&ndash;server architecture is not required. A standalone program that runs on the local machine will suffice. ## Team Why a team project? Because... * Working in a team helps hone skills needed to be effective in the workplace, where teams are the norm. * Working in a team affords the opportunity for parallel development activities and specialized expertise. * Working in a team offers you the powerful tool of discussing ideas with others. **Team formation:** You are responsible for forming your own team. You can use the team formation features of Piazza to help with this. **Team size:** Your team may have three or four members, at your choice. Two member teams are not permitted: we want you to experience programming in a larger group, in which communication challenges arise. Five member or larger teams also are not permitted, as the scope of the project does not warrant that many human resources. **Personnel changes:** You are permitted to change teams between milestones, although we discourage doing so unless it becomes necessary for reasons of interpersonal conflict. ## Objectives * Design and implement a small system of about a couple thousand lines of code. * Practice building software as part of a team. * Integrate the material you have studied throughout this semester. ## Technologies You must use OCaml to implement your system. You may use any packages available through OPAM that work on the 3110 VM. If you have questions about whether you can use other third-party code or tools, then ask, rather than assuming one way or the other. You are required to use [Git][git] (or another version control system) throughout the implementation phase of your project. **Private repos are of the utmost importance. A public repo would share your code with the entire world, including your classmates, thus violating the course policy on academic integrity. Therefore we require that you keep all your CS 3110 related code in private repos.** [git]: https://git-scm.com/ ## Grading Your grade will be influenced by the quality and non-artificiality of your project. Projects that are exceptional in scope and quality might, at the instructor's discretion, receive a bonus of up to 10% on the final milestone. The primary way to achieve this bonus is to build a system that is new and exciting. *New* means that your system should have some aspect that is novel, rather than just replicating some existing system. *Exciting* means that your system should have some aspect that provokes a response of "hey, that's cool!" In the ideal case, the exciting aspect of your software is also new. In that case, you might become rich and famous. :) * * * ## <a name="ms0"></a>Milestone 0: Charter **Soft and hard deadline:** Monday, 11/02/15, 11:59 pm Your task in this milestone is to form a team and decide what you want to build. **What to submit:** A file named `charter.pdf` containing the following information: * **The members of your team,** including their names and NetIDs. * **Your plan for a regular status meeting.** We strongly recommend that, as a team, you agree on a regular meeting time and place (outside of class) that you can attend to discuss the status of your project. Meeting at least every two days is advisable, especially during the implementation phase of the project. * **A proposal for your system.** Summarize the system you intend to build. Tell us what will be the most important functionality of your system. This summary should be about one page long. Provide: - a very short statement of the core vision or key idea for your system, - a short (no more than six items) bulleted list of the key features of the system, and - a narrative description of the system you intend to build. Go into enough detail that, if your charter were given to another team, and that team were never allowed to talk to you, they could still build more or less the system that you have in mind. * * * ## <a name="ms1"></a>Milestone 1: Design **Deadlines:** same as A5 **Soft deadline:** Thursday, 11/12/15, 11:59 pm **Hard deadline:** Saturday, 11/14/15, 11:59 pm Your task in this milestone is to think carefully through the design of your system before you write any code. **What to submit:** Prepare a *design document* named `design.pdf` containing the following information: * **System description:** Include your system proposal (core vision, short bulleted list of key features, and narrative description) from Milestone 0, updated to account for any changes you have since made. * **Architecture:** What are the components and connectors? Include a components and connectors (C&C) diagram. * **System design:** What are the important modules that will be implemented? What is the purpose of each module? Include a module dependency diagram (MDD). * **Module design:** What is the interface to each module? Write a `.mli` file making each interface precise with names, types, and brief specifications (which you will plan to elaborate later); submit a zip file named `interfaces.zip` containing those `.mli` files along with your design document. * **Data:** What data will your system maintain? What formats will be used for storage or communication? What data structures do you expect to use as part of your implementation? * **External dependencies:** What third-party libraries (if any) will you use? * **Testing plan:** How will you test your system throughout development? What kinds of unit and module tests will you write? How will you, as a team, commit to following your testing plan and holding each other accountable for writing correct code? Your design document should be about 1000 words, excluding the system description, diagrams, and `.mli` files. Keep the formatting simple and easily skimmable: a reader should be able to look at the document quickly and get the basic idea, and quickly identify where to go for details. In practice, this means: * Lots of subheadings and very short paragraphs. * Appropriate usage of font size and bold to draw reader attention. * Information early in the document should be short and punchy. * Complicated details should be left to the very end. * * * ## <a name="review"></a>Design review meeting **Deadline:** Saturday, 11/21/15, 11:59 pm During the week after you submit your design document, you will have a *design review meeting* with a member of the course staff. <!--Further instructions will be posted on Piazza. --> There is an assignment of teams to staff posted on Piazza. Please look at it to determine the staff member assigned to your design review meeting. Contact that staff member to schedule a 30 min appointment outside of regular consulting hours before the deadline (given above). Contact them ASAP; it is not their responsibility to accomodate you at the last minute if you fail to schedule an appointment well in advance. All your team members are required to attend. The only new thing you need to bring to your meeting is an *implementation plan*: a schedule of what you plan to implement by when. Here's the agenda for your design review meeting: * Introductions and overview [2 min]: The staff member begins the meeting. (We suggest that the team appoint one member as a note-taker for the meeting.) * Background [3 min]: The team gives a brief reminder of project and overview of design, especially highlighting any changes that might have occurred since submitting design document. * Discussion of design [21 min]: The team and staff member discuss the design. The staff member will come prepared with questions and constructive feedback. * Planning [3 min]: The team presents its implementation plan to the staff member. * Wrapup [1 min]. This meeting will account for about 1/3 of your grade for the design phase of the project. All team members are expected to be familiar with the team's project effort, and the team as a whole will be held accountable for that. Of course, it makes sense for certain team members to be subject matter experts on pieces of the design (e.g., front-end vs. back-end, or AI vs. game logic). * * * ## <a name="ms2"></a>Milestone 2: Implementation **Deadlines:** same as A6 **Soft deadline:** Thursday, 12/03/15, 11:59 pm **Hard deadline:** Saturday, 12/05/15, 11:59 pm Your task in this milestone is to implement your system. **What to submit:** * `src.zip`, containing the source code of your system. Make sure to include all the files necessary to compile and run your system. In that zip file, include a file named `README.txt` with clear instructions to the grader on how to compile and run your project. As always, your code must be written with good style and be well documented. * `vclog.txt`, containing your version control log. * `design.pdf`, which is an updated version of your design document: - Account for any changes made during implementation. - You do not need to submit a separate `interfaces.zip` for this milestone, because you're already submitting those files as part of `src.zip`. - Update the test plan to discuss what you accomplished and describe any known bugs. - Add a new section on **Division of labor**: Who implemented what? Write a paragraph for each team member describing their primary contributions to the implementation effort. Include an estimate of how many hours each person worked. **Grading issues:** * **Compiling and running:** Your project must compile and run by following the instructions you provide in your `README.txt` file. If, by following those instructions, a grader cannot compile and run your project within a timespan of about five minutes, your project will receive minimal credit. * **Code style:** Refer to the [CS 3110 style guide][style]. Ugly code that is functionally correct will nonetheless be penalized. Take extra time to think and find elegant solutions. * **Late submissions:** Carefully review the [course policies][syllabus] on submission and late assignments. Verify before the deadline on CMS that you have submitted the correct version. * **Environment:** Your solution must function properly in the [3110 virtual machine][vm], which is the official grading environment for the course. [style]: http://www.cs.cornell.edu/Courses/cs3110/2015fa/handouts/style.html [syllabus]: http://www.cs.cornell.edu/Courses/cs3110/2015fa/syllabus.php [vm]: http://www.cs.cornell.edu/Courses/cs3110/2015fa/vm.html [cms]: https://cms.csuglab.cornell.edu/ * * * ## Hints Here is some sarcastic (and hopefully humorous) [advice on how to lose in a group project][advice]. Although it was written for CS 2112, it's applicable to CS 3110 as well. [advice]: http://www.cs.cornell.edu/Courses/cs2112/2015fa/hw/how-to-lose.html ## Appendix: Teamwork [added 11/03/15] At your first meeting, read the questions on teamwork in the provided `a5.txt`. Since you'll need to answer them by the time you submit your solution, now would be a good time to take a few minutes to talk about what you hope your answers will be. You are especially encouraged to write down a short set of ground rules for your team. Here are two sample sets of ground rules that you might use as a starting point for discussion: * Everyone will participate and take ownership of our work. * When appropriate, sub-teams will be assigned to work on specific activities. * Team members will complete assignments on time. * Meetings will start and end on time. No backtracking if someone is late. * Each meeting will have a note taker (rotating task) who will distribute notes and record decisions and assignments. * Anyone who is absent from a meeting is responsible for finding out what they missed. * Everyone will respect the value of each individual's contribution. * Resolution of differences will typically be by majority decision, but on key issues the team will reach consensus. (Source: [University of Minnesota Office of Human Resources][umhr]) [umhr]: http://www1.umn.edu/ohr/toolkit/workgroup/forming/rules/ * We all show equal commitment to our objective. * We all take part in deciding how work should be allocated. * We are committed to helping each other learn. * We acknowledge good contributions from team members. * We handle disagreements and conflicts constructively within the team. * We are able to give constructive criticism to one another and to accept it ourselves. * We all turn up to meetings and stay to the end. * We are good at making sure that everyone knows what's going on. * When one of us is under pressure, others offer to help him or her. * We trust each other. * We remain united even when we disagree. * We support each other to outsiders. * We feel comfortable and relaxed with one another. (Source: [University of Waterloo Centre for Teaching Excellence][teamwork], citing Levin and Kent (2001).) [teamwork]: https://uwaterloo.ca/centre-for-teaching-excellence/teaching-resources/teaching-tips/tips-students/being-part-team/teamwork-skills-being-effective-group-member