6.031 — Software Construction
Spring 2017

Project: Norn Mailing List System (Phase 1)

Team contract due
Wed Apr 12, 10pm
Warmup due
Wed Apr 19, 11am
Specs due
Fri Apr 21, 10pm
Project deadline
Mon Apr 24, 10pm
Reflection deadline
Wed Apr 26, 10pm

Mailing list systems, like MIT’s WebMoira, are great in part because they are recursive: lists can contain other lists. So course6-all can include course6-students and course6-faculty, and course6-students can include course6-undergrads, course6-grads, and course6-alumni.

But a mailing list system would be even more useful if it could:

  • intersect mailing lists: course6-undergrads intersected with mydorm would let you find the Course 6 undergrads who live at mydorm.
  • omit individuals or lists: myfloor omitting benbitdiddle would let you plan a surprise party for Ben.

This project asks you to build an expressive mailing list system called Norn (the Norse equivalent to Moira). The system should be able to process a list expression whose meaning is a set of recipients that might be pasted into the To: field of an email message. You will use ParserLib to parse list expressions and a recursive data type to represent them, and other abstract data types of your own design to manage the mailing lists that have been defined.

In Phase 1 of this project, you will practice working in a small group, using the software engineering techniques we have learned so far this semester: version control, specifications, unit tests, immutable data, abstract data types, and so on. You will also get more practice with grammars, parsers, and abstract syntax trees.

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. 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

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/norn1 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/sp17/projects/norn1/username1-username2-username3.git norn1

    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. You will need to write a grammar for parsing list expressions; design an immutable recursive abstract datatype (an AST) for those expressions; design an abstract data type for storing list expressions that have been given mailing list names; design a frontend that interacts with the user at the console; and other components.

    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 safety from rep exposure.

  • 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.

  • 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:

Parser

AST

Frontend

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 mailing list system must work for this phase of the project.

Provided code

Your starting repository has a Main class that implements a simple interactive loop, reading one line at a time from the user.

You may also find earlier staff-provided code to have useful models, or even starting points, for your design and implementation:

Warmup

As your first step in this project, make progress on each of the three major pieces of Phase 1:

  1. Use a ParserLib grammar to create a parser that recognizes a small subset of list expressions: specifically email addresses separated by commas, such as bitdiddle@mit.edu,alyssap@mit.edu,louis@gmail.com. Note that you are required to use ParserLib for this project.

    Remember that you are working towards handling the full list expression language, so design your initial grammar as a step in that direction. For example, think about the comma , as a binary operator, since it will eventually be joined by other binary operators * and !.

  2. Create an abstract syntax tree type, which should be an immutable recursive datatype, that is able to represent that subset of list expressions, and define an operation that computes the set of recipients represented by an expression. For example, the result of the expression bitdiddle@mit.edu,Bitdiddle@mit.edu,alyssap@mit.edu should be (abstractly speaking) the set {bitdiddle@mit.edu, alyssap@mit.edu}.

    Again, remember that you are working towards handling the full list expression language, so design your initial AST type with the expectation that the , binary operator will be soon joined by other binary operators * and !.

  3. Modify Main.java so that it acts as an interactive frontend for your parser and interpreter. The user should be able to type bitdiddle@mit.edu,Bitdiddle@mit.edu,alyssap@mit.edu and see the set {bitdiddle@mit.edu, alyssap@mit.edu} printed out in some form, even if it’s not (yet) the form required by the spec.

This is an initial iteration, but you should still include a first draft of specs, tests, recursive datatype definitions, rep invariants, abstraction functions, and equals()/hashCode()/toString() defined where appropriate.

Deliverables and grading

Wed Apr 12, 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 Apr 19, 1pm
Milestone meeting: you will have a meeting with your group’s TA mentor, at which you must demonstrate the deliverables described under warmup.
Commit code and specifications to your group’s repository by Tue Apr 18, 10pm. You will demo the code and discuss your work at the meeting. Have a laptop with the program ready to run.
Fri Apr 21, 10pm
You should have committed (1) a grammar for the complete list expression language, (2) specs for all your classes and methods, and (3) some progress on testing and implementation.
Mon Apr 24, 10pm
Project deadline. Your specifications, tests, and implementation should be complete and committed to your group’s repository.
Wed Apr 26, 10pm
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 warmup 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:

  • Wed Apr 12
  • Fri Apr 14
  • Wed Apr 19 (this is the milestone meeting)
  • Fri Apr 21
  • Mon Apr 24

Additional pages referenced above

Norn specification

Automated testing

Team contract

Reflection