Evaluation criteria for machine problems

For style specifics, please see the machine problem style guidelines.
 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

Last modified: Mon Feb 26 21:06:40 EST 2007