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 
       module should be able to use your function by simply having access to the 
       contract and its purpose statement. 
   
       - honor your contracts. Make sure that your implementation and your 
       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. 
   
       - indent your code appropriately. 
   
       - lines should be 80 chars long NOT LONGER 
   
       - make it clear what your modifications are. For tests add all your tests 
       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