# FAQs for Machine Problem 5

1. Do I need to add +, sub1, etc, to my language?
Yes.  It's easy.

2. Do I need to have multiple arguments, etc., in my statement language?
Yes.  In general, our languages are intended to be cumulative.  This
should be a simple matter of cut-and-paste.

3. Are we supposed to modify the existing "let", etc?
> For the first two questions, are we supposed to add new productions
> for "let", etc., or just modify the ones that are already in the grammar?

Yes.  You will need to modify the existing let-exp

4. How are machine problems graded? Here is what last year's TA (Theo) wrote. It's still accurate.
Points in general are allocated on

(a) Program correctness. Your interpreter does the right thing.

(b) Program design.

(1) One task one function. Common tasks are factored out into a
function.

(2) Each newly created function comes with a contract, purpose and some
examples.

(c) Test coverage. You should add enough tests to check that new features
of your interpreter work as expected. This means, check each feature on
its own, both simple and complex cases. Check combination(s) of features,
both between the new features and new features and old features.

So what we are grading is not just that the interpreter behaves as required
by each machine problem. What we grade is your solution. Code is not just to
be executed, it's to be read, understood and evolved by programmers.

Having said that what follows is a list of common sources of confusion based
on what we have seen thus far in your solutions. (references in square
brackets can be found at the end of the email message)

contracts [1]
- should be as strict as possible. i.e. schemevalue -> schemevalue covers
any function that you can write but it's not informative enough. Another
contract and its purpose statement.

contract are in sync
(a)  If the output of a function is a number, then I expect a number and
nothing else.

(b) If your function is to throw an error make sure your contract
specifies that too.

(c)  If your contract specifies that it expects a number as input then
there is no need to check your input is a number, or anything else (i.e.
null? tests on inputs that are specified to be non-lists).

- examples should be examples. If you give examples in comments that are
wrong that is an indication that you are not completely aware of what is
going on with the code.

- modifications that alter the behavior of an existing function *need* to
also change the function's contract. Changing a function in a way that
changes its original contract dictates a redefinition of the contract.

- FOLLOW THE DESIGN RECIPE [2][3]. We have noticed that some "easy" bugs
could have been avoided if people followed the design recipe.

rules
- should explain the behavior of the interpreter's feature you are coding
up. A specification is all one needs in order to implement the feature. So
make sure you cover all cases and there are not ambiguities. If your
partner can't figure out the rule and has questions about how to deal with
different situations, then that is a sign that your rule is not specific
enough.

- rules are *not* code. You can refer to standard things in your code i.e.
expval-> bool but you cannot write snippets of Scheme code. The rules tell
you "what" you have to do. The implementation tells you "how" to do it.

implementation
- Keep it simple, keep it clean. Before submitting code remove/comment out
any debugging code you have added.

- do not create new ast nodes inside the interpreter.

- lines should be 80 chars long NOT LONGER

before or after the ones that are provided for you.

- dead code will cost you points! If you have code that never gets called
(besides debugging code) remove it.

development diaries

- Provide totals for Time and Lines of modified/added code.

These are some of the common issues that we have
encountered and have caused people to lose points.

[1] http://en.wikipedia.org/wiki/Design_by_contract
[2] http://htdp.org/2003-09-26/Book/curriculum-Z-H-5.html#node_sec_2.5
[3] http://www.ccs.neu.edu/home/skotthe/csg111/lab1.html