Missionary and Cannibal grading guide  [2001.fall hw09]

This grade guide, while readable by students,
is targeted at labbies, so not all issues may be explained in detail.

This is strictly supplementary to the master hw-grading guide.





Things to look for:

- Adequate descriptions of data def'ns.
     "A state is (make-state <num> <num> <symbol>)
      (define-struct state ncl ncr bs)"
  isn't helpful to a reader, without additional commentary:
     " ncl is the Number of Cannibals on the Left  bank;
       ncr is  "    "    "     "      "  "   Right bank, and
       bs ("boat-side") is either 'left or 'right."

  Note that descriptive variable/field names *do* count as self-documantation;
  e.g. using the field "num-cannibals-right" doesn't need further
  comment, since you can assume the reader of the code has
  read the assignment handout.

  It's a judgement call, what counts as and intuitive enough name
  to not need comments.

  Even if somebody uses a field name "boat-side", there should
  be some comment about its possible values (e.g. "either 'left or 'right").


- Note that actually, the constants 'left and 'right are magic constants,
  and shouldn't be in the code (e.g. if somebody later uses constants
  'wrong and 'right, it becomes difficult to change representations).
  Ideally, use named constants like LEFT, RIGHT.
  Only -1/2 for this.


- Point of note:
  Should a state  include the #cannibals on *each* side of the
  river, or just one (say) the left side?
  Including the #cannibals on both sides brings up conflicting issues:
  - it more naturally reflects most people's thinking
     (witness the fact that in our sketches of the game,
     we really did draw dots on boths sides of the river),
    but
  - including redundant information 
    introduces the possibility of mistakenly having an inconsistent state.

  We won't take off any points for either approach, since
  we haven't discussed this in class.

  Solution(s):
   - worst: 
     include the number on both sides, and just cross your
     fingers and hope you don't have any bugs which introduce
     nonsensical states:
   - better: 
     include the number on both sides,
     but have a sanity-check function which checks a state's consistency.
     Call this function periodically (or as much as, after every state-change).
     E.g. the function "legal-state?" is a natural place to check this.
   - best:
     have a state only include the # on the left side,
     BUT have a function state-cann-right: state --> natNum
     which computes the number on the right side.
     This is best: it eliminates redundancy, but
     (by reflecting our thinking of the problem)
     it aslo tends to allows for easy future modification --
     say, if someday #left doesn't determine #right (say,
     people can be eaten or converted in transit :-)



-----------------
From: "Bill Hodges" <bhodges@rice.edu>
Subject: Re: hw09-gradeguide
Date: Wed, 14 Nov 2001 02:00:05 -0600

On Missionaries and Cannibals, I have just a couple preliminary issues:

- Helper functions are good when many different ones are used within a
local, in this way modularizing the code, but it's important to use names
that mean something (I had a guy write use helpers "opbltos", "opmctomc",
"change", and "helper").  I prefered that the names were more intuitive (and
definately not just "helper") so that the final code segment fits together
better and makes more sense just from reading.  This isn't a back-breaking
problem, so I don't plan to take but a point or two for all such occurences.
- As usual, people are short on data examples.  Some people left them out
all together.  Since this is about as important as anything on this project,
I plan on taking off a chunk for this.
- Helpers should be in local, but some still did external helpers (boy, does
this get messy.)  I'm thinking 2 points, since its really hard to read and
understand, when parameters are getting repassed when they could be
inherited in a local, etc..
- I've had people adding little "hacks" just to "make things work out."  I'd
imagine we prefer people to be more rebust from the word go, and such little
problems ususally work themselves out.
- I had a guy represent a boat position as (make-boatload right left) where
right and left are booleans.  This hasn't been a common problem

Other than this so far, Ian's comments have covered what I've seen so far.

Bill