7 — The Clean Up 🔗

Due Thursday, 02 November 2023, 11:59:59pm

Delivery Place the product of this week’s milestone into your git repo as follows:

Programming (Clean-up) Tasks Like all software projects, yours has accumulated a significant technical debt, partly due to the usual kinds of disagreement between your "customer" and you, mostly due to the usual deadline stress.

Your team manager has decided that the project needs to reduce this debt now that you have a new partner. This will give you a chance to work through design rationales, rewrite or document all difficult to decipher code snippets, and reassess the qualities of the code base in general.

Step 1 Compile a list of todo items and priority-rank them. Commit and push as todo.md.

For sources of problems, consider the feedback you have gotten for the past six milestones. Still-failing integration tests should get the highest priority. Also, revisit all those purpose statements, complicated methods, overly large functions, and unit-test suites about which the TAs/reviewers complained.

Step 2 Work through this todo list. As you complete an item, move it from the todo list to a separate section, entitled “Completed.” Add the git commits plus the commit messages that fix the issue.

The TAs will cross-check that at the end all git commits are accounted for.

Guidance A clean-up task should always look forward, attempt to anticipate how the software may evolve. Here we provide two explicit prompts. The first is a required code revision; the second is the design task, which does not affect the current programming task but may affect future tasks. Additionally, the testing task may demand “pay down” but, in principle, it should not. It essentially asks for a minor revision of your test script from 6 — Games!; the referee component and the player directory should already implement the functionality.

Required Revisions While you clean up your code, change your program so that the bonus for placing a Q could be set to 8 and the one for finishing the game could be set to 4 for the next milestone and even different values later on.

Pedagogy Implementing this change may point out infractions of rather basic design rules that may have significant repercussions in terms of technical debt. Think of them as simple examples.

(Re)Design Task The co-CEOs are considering changes to the rules and would like to know from their development team how difficult it would be to accommodate one or all of the following changes:
  • changing the bonus points again and allow more players to participate in a game;

  • adding wildcard tiles;

  • imposing restrictions that enforce the rules of Qwirkle instead of Q.

Study the impact of each change on your code base. Rank it on a scale of 1 (extremely easy) to 5 (extremely hard) and explain your choice with one to three complete sentences. The memo in changes.md should not take more than a page.

Note The decision has been made. Your answer will not influence the choice.

Testing Task Create a test harness named xgames. The harness consumes its JSON input from STDIN and produces its results to STDOUT. Create ten tests ([0-9]-{in,out}.json) and place them in the specified Tests/ folder.

A test case always consists of given inputs and expected outputs. For this course, a test consists of a pair of files: n-in.json, the input file, and n-out.json, the expected output file, where n is an integer between 0 and the requested number of tests (exclusive).—Constraint No test file may exceed the size limit of 40Kb.

The inputs of xgames consist of a JState followed by aJActors array of JActors. The test harness creates a series of players that are going to use the specified strategies. It then hands these players and the given state to the referee, which runs the game to the end and computes the names of the winner(s) and drop-out(s). (The details will depend on your referee interface and data representations.)

The output is an array of two arrays: (1) the first contains the alphabetically sorted (string<=?) JNames, of winners and (2) the second the event-sorted JNames of dropout players, meaning the drop-out list enumerates the names of the player in the order in which they got kicked out.

The referee kicks out a player for the specified forms of misbehavior during any interaction. Once a player is kicked, the referee acts as if it had never been a part of disappeared from the game on the spot and it is reported as a misbehaving player. (Why?)

Here are the relevant data definitions:

    JState is an object with three fields:

      { "map"      : JMap,

        "tile*"    : [JTile, ..., JTile],

        "players"  : [JPlayer, ..., JPlayer] }


     INTERPRETATION Describes the referee's current knowledge about the

      map and all players between two complete rounds of game play.  The

      first item in "players" denotes the currently active player,

      and the array specifies the order in which the players take turns.

      The "tile*" field specifies in which order the referee

      hands out tiles.


      Tiles are always treated as ordered lists, and adding tiles is done via append.


     CONSTRAINT The "players" must be non-empty.


    A JActors is a JSON array of JActorSpecs:

     [JActorSpec, ..., JActorSpec]


     CONSTRAINT A JActors contains at least 2 and at most 4

      players i.e. JActorSpec.


    A JActorSpec is one of:

      - a JSON array of two elements: [JName, JStrategy]

      - a JSON array of three elements: [JName, JStrategy, JExn]


     INTERPRETATION Denotes either a one well-behaved and exception-raising player.


    A JName is a string of at least one and at most 20 alpha-numeric

     characters, i.e., it also matches the regular expression "^[a-zA-Z0-9]+$".


    A JExn is one of: "setup","take-turn","new-tiles","win".


      A good strategy [n, s] denotes a player named n that pursues

      the legally, iterated version of strategy s throughout the game.


      A bad strategy [n, s, b] denotes a player named n that pursues strategy s

      until method b is called. When b is called, the method raises an exception.


     CONSTRAINT The names of any two different JActorSpecs must be distinct.


     GLOBAL CONSTRAINT The array of JPlayers in JState contains as

      many players as the JActors.



     GLOBAL INTERPRETATION The referee's knowledge about players is in the same

      order as those in the given JActors specification.