<
* [Milestone 1 (Design)](#ms1), followed by [design review meeting](#designreview)
* [Milestone 2 (Prototype)](#ms2), followed by [prototype review meeting](#prototypereview)
* [Milestone 3 (Implementation)](#ms3), followed by [demo](#demo)
## 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. The game might be
two-player (like [Battleship][battleship]) or multi-player (like
[Texas Hold'em poker][holdem]). Humans might be able to compete
against themselves, another human, or against AIs. Beware that a game
in which players act simultaneously in real time could be considerably
challenging to implement; we recommend that you instead choose a game
in which players take discrete turns.
* **Programmable calculator.**
Build a programmable calculator. Your calculator could have a REPL
in which users can enter not just simple arithmetic expressions,
but could also write programs in a small language of your design.
You could be inspired by the [RPL language][rpl].
You calculator could solve systems of equations or plot functions.
* **Bulletin board.**
Build an online bulletin board. Discourse, Piazza, Facebook, and
Wikipedia are examples in this genre. Users post content which
other users can explore and interact. Users can search for content
of interest. Provide a server application, which could be accessed
by a web browser. Or perhaps you'd prefer to build a custom client
application.
* **???.**
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
[text]: http://caml.inria.fr/cgi-bin/hump.en.cgi?sort=0&browse=64
[rpl]: http://documents.epfl.ch/users/f/fr/froulet/www/HP/RPL/usr_toc.html
*Non-requirements:* A graphical user interface is not required. Text-based
interfaces will suffice. Similarly, a client–server architecture is
not required. A standalone program that runs on the local machine will suffice.
Be warned that networking and GUIs can be difficult, and that most of the
course staff will not have experience with those (at least not in OCaml)
to help you. So if you want to go for such a project, start building
a prototype of that functionality early. And have a backup plan in case
it becomes too hard to get done in time.
*Further inspiration:* The [winners of last fall's Staff
Choice awards][tournament2017fa] built a keyboard music player and two games.
You, too, have the opportunity to be immortalized
on the 3110 Tournament Page! To be eligible for the Staff Choice
award, your system must be easily deployable on the course VM following
the install instructions you include with your final submission.
[tournament2017fa]: http://www.cs.cornell.edu/Courses/cs3110/archive/tournaments.html#fa2017
## 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
OCaml code. That's not a hard requirement, just an estimate. You're
free to have a "mixed language" project that includes source code in
Python or Java, etc., but since 3110 is a functional programming course,
what matters is the size of the OCaml fragment of your system.
* 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. As always, you
must use a private repo. After the project is over (i.e., when the
semester ends and you have received your grades), you are welcome to
open source your software and make it public.
[git]: https://git-scm.com/
## Grading
Your grade will be influenced by the quality and non-artificiality of
your project.
Of the total percentage dedicated in the syllabus to the final project,
we expect the breakdown between milestones to be as follows:
* MS0: 5%
* MS1: 15%
* MS2: 15%
* MS3: 65%
Projects that are exceptional in scope and quality might,
at the professor'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
**Deadline:** Thursday, 03/15/18, 11:59 pm, *no late submissions allowed—submit
what you have by the deadline*
Your task in this milestone is to form a team and decide what you want
to build.
**What to submit:**
A 1-page document 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 would still understand more or less the
functionality that you have in mind. But keep it to a single page.
* * *
## <a name="ms1"></a>Milestone 1: Design
**Deadline:** Thursday, 03/29/18, 11:59 pm, *no late submissions allowed—submit
what you have by the deadline*
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.
**Assessment:** Your design document and interfaces (i.e., `.mli`
files) will account for about 80% of your MS1 grade. You will be
assessed on whether your design document includes all the information
that is requested in sufficient detail for the grader to understand it.
You will also be assessed on the level of detail in your interfaces
(i.e., `.mli` files), including the completeness of your design and the
specifications found for the modules and functions in them. The design
document and interfaces will be weighted about equally.
* * *
## <a name="designreview"></a>Design review meeting
**Occurs during:** Monday, 04/09/18 through Friday, 04/13/18
After design documents are due, you will have a
*design review meeting* with a member of the course staff.
You will choose a staff member using the CMS scheduling feature. Contact
that staff member to schedule a 30 min appointment outside of regular
consulting hours before the deadline (given above). Contact them ASAP
after the schedule is made available; it is not their responsibility to
accomodate you at the last minute if you fail to schedule an appointment
well in advance.
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].
**Assessment:**
Your performance at and preparation for this meeting will account for
about 20% of your grade for MS1. 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). All your team members are
required to attend. Any absent team member will incur a 10% penalty for
themselves (not the rest of the team) on their MS1 grade.
* * *
## <a name="ms2"></a>Milestone 2: Prototype
**Deadline:** Tuesday, 05/01/18, 11:59 pm, *no late submissions allowed—submit
what you have by the deadline*
Your task in this milestone is to produce a preliminary prototype that
demonstrates *some* of the functionality of your final system. A good
way to demonstrate functionality is using tests that exercise the code
in some of the components of your system. (It's totally fine if you do
not yet have any end-to-end tests running by Milestone 2.)
**What to submit:**
Prepare a *document* named `status.pdf` containing the following information:
* **System description:** Include your system proposal and design
document from Milestones 0 and 1, updated to account for any changes
you have since made.
* **Changes:** Highlight any major changes you have made to the
project since the design review meeting and briefly discuss your
reasons for making these changes.
* **Status:** Describe what pieces of your project you have
implemented so far.
* **Roadmap:** Describe what functionality remains to be implemented
and how you plan to complete it.
* **Testing:** Describe what tests you have been able to successfully
run. Submit a file `prototype.zip` containing your current prototype
and tests.
Your document should be about 1000 words, excluding any supporting
diagrams and any other 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.
**Assessment:** Your prototype document and tests (i.e., `.ml` files)
will account for about 80% of your MS1 grade. You will be assessed on
whether your design document includes all the information that is
requested in sufficient detail for the grader to understand it. You
will also be assessed on the level of completeness and sophistication
for your tests (i.e., `.ml` files). The design document and tests will
be weighted about equally.
* * *
## <a name="prototypereview"></a>Prototype review meeting
**Occurs during:** Wednesday, 05/02/18 through Tuesday, 05/08/18
After design documents are due, you will have a *prototype review
meeting* with a member of the course staff.
You should contact the staff member who did your design review meeting
to schedule a 30 min appointment outside of regular consulting hours
before the deadline (given above). Contact them early; it is not their
responsibility to accomodate you at the last minute if you fail to
schedule an appointment well in advance.
Here's the agenda for your prototype 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 the design review.
* Discussion of prototype [21 min]: The team and staff member discuss the prototype. The
staff member will come prepared with questions and constructive feedback.
* Planning [3 min]: The team presents its roadmap to the staff member.
* Wrapup [1 min].
**Assessment:**
Your performance at and preparation for this meeting will account for
about 20% of your grade for MS2. 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. All your team members are
required to attend. Any absent team member will incur a 10% penalty for
themselves (not the rest of the team) on their MS2 grade.
* * *
## <a name="ms3"></a>Milestone 3: Implementation
**Deadline:** Tuesday, 05/15/18, 4:30 pm, *no late submissions allowed—submit
what you have by the deadline*
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.
* `gitlog.txt`, containing your Git 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.
* **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.
[style]: http://www.cs.cornell.edu/Courses/cs3110/2018sp/handouts/style.html
[syllabus]: http://www.cs.cornell.edu/Courses/cs3110/2018sp/syllabus.php
[vm]: http://www.cs.cornell.edu/Courses/cs3110/2018sp/install.html
[cms]: https://cms.csuglab.cornell.edu/
**Assessment:** The files you submit will account for about 75% of your
grade on MS3. You will be assessed on the scope of your system (about
50%), the quality of your code (about 12.5%), and your testing
methodology (about 12.5%). The latter two will be assessed much as they
have been on assignments all semester. For scope, we will be assessing
the difficulty and extensiveness of the system you implemented. Systems
that are comparable in difficulty and size to the sample systems above will
usually receive grades in the B range. Systems that are significantly more
impressive (perhaps because of interfaces, networking, feature set,
algorithmic difficulty, or master of new libraries) will receive grades
in the A range. Systems that are comparable in difficulty or size to early
course projects, like A1 and A2, will receive grades in the C range.
"Difficulty" here means the difficulty that they posed at that time,
before you had learned functional programming or (e.g.) Yojson—not
how difficult they would be to resolve now.
* * *
## <a name="demo"></a>Demo
**Occurs during:** Monday, 05/14/18 through Friday, 05/18/18
After the final implementation is due, you will have a
*demo session* with a member of the course staff.
You will meet with the same staff member who held 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.
Here's the agenda for your demo:
* Introductions and overview [2 min]: The staff member begins the meeting.
* Background [3 min]: The team gives a brief reminder of project,
especially highlighting any changes that might have occurred since the
design phase.
* Demo of system [24 min]: The team presents the implemented functionality,
demoing the features of the system that are working, and discussing any
planned functionality that wasn't completed. You must demo what you turned
in as of the Milestone 3 deadline; sorry, but for fairness to other teams
we can't allow you to continue improving the system after that.
* Wrapup [1 min].
**Assessment.**
Your demo will account for about 25% of your grade on MS2. Your demo
will be assessed on the perceived quality of your system. Excellent
demos will have no errors or crashes, an intuitive user interface, will
get started immediately without any difficulties of launching or
configuring the system, and all features will be working as expected.
All your team members are required to attend. Any absent team member
will incur a 10% penalty for themselves (not the rest of the team) on
their MS2 grade. Each day after 12/11 that your team is late in having
its demo will incur a cumulative 25% penalty on your team's MS2 grade.
* * *
## 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
At your first team meeting, we strongly encourage you to write 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
]]>