Coding guidelines

1. Comments
   
   Each procedure you write, including all helper procedures, should have a concise and clear description of the procedure, the arguments, preconditions, and return values.
   
   
2. Indentation
   
   We should be able to tell the structure of your procedure simply by looking at it. I.e. it should be very clear what is a procedure call, what are the arguments to a procedure, what is the condition in the if (or cond) statement, and what is the consequent.
   
   For example:
   
   Bad:
     (define (length x)(if (null? x) 0 (+ 1 (length (cdr x)))))
   
   Good:
   (define (length x)
      (if (null? x) 0
           (+ 1 (length (cdr x))))))
   
   You are encouraged to use a good editor (e.g. Emacs) that indents the code for you.
3. Efficiency
   
   You do not have to go out of your way to optimize your algorithms. However, your code should be reasonable. You should not be evaluating the same thing multiple times, for example. You should not traverse lists unnecessarily.
   
   
4. Style
   
   Your code should be nice. Of course, it is difficult to say what "nice code" is. Use your judgment.
   
   if condition then do A
   else do A
   
   is not a "nice" piece of code.
   
   if x >= 0 do A
   if x < 0 do B
   else do C
   
   is not a "nice" piece of code either.
   
   It should be clear to the reader that your code does not work by some magic simply because you tried 10000 different versions and one of them finally worked. It should be clear that you know what you are doing.
   
   Your should pick informative names for your helper procedures, as well as for all arguments.
   
   
5. Things NOT to do
   
   
   • call your procedures help, helper, helper[1-N], myfunction-help
     
   • (append (list x) y)     Instead: (cons x y) 
     
   • (cons x (cons y (cons z (list a (append b) (append w (list v)))))))...
     
   • if ... cond ... if ... if .... cond .... else .... if .... ....

General coding guidelines

• Correctness
  
  The program should conform to the specifications for which it was written. It should include correct handling of special cases, except that you may assume that input will be provided in the specified format (i.e. you can use programming-by-contract)
  
  
• Design and Efficiency
  
  The program should be constructed from small, coherent, independent and loosely coupled functions. Each function should access only its own parameters. The control constructs and data structures used should be those appropriate to the problem at hand. The program should not perform unnecessary steps, use extraneous variables, nor implement the algorithm in a contorted or inefficient way.
  
  
• Style and Documentation
  
  The program should conform to generally accepted principles of style, such as a consistent pattern of indentation, use of meaningful identifiers, generous use of space, etc. Internal documentation should include program and procedure headers, and in-line comments to clarify the code.
  
  

[Home|Assignments]