Question

I’ve been learning scheme, and I just realized that I don’t really know how to properly comment my functional scheme code. I know how to add a comment of course – you add a ; and put your comment after it. My question is what should I put in my comments, and where should I comment for maximum readability and comprehensability for other programmers reading my code?

Here’s a code snippet I wrote. It’s a function called display-n. It can be called with any number of arguments and outputs each argument to the screen in the order that they are provided.

(define display-n
  (lambda nums
    (letrec ((display-n-inner 
              (lambda (nums)
                (display (car nums))
                (if (not (equal? (cdr nums) (quote ()))
                    (display-n-inner (cdr nums))))))
      (display-n-inner nums))))

Edit: Improved tabbing and replaced '() with (quote ()) to avoid SO messing up the formatting.

I’m just not sure how/where to add comments to make it more understandable. Some scheme code I’ve seen just has comments at the top, which is great if you want to use the code, but not helpful if you want to understand/modify it.

Also – how should I comment macros?

Answer 1

The common style for Lisp comments is

• Four semicolons for commentary on a whole subsection of a file.
• Three semicolons for introducing a single procedure.
• Two semicolons for a description of the expression/procedure definition on the following line.
• One semicolon for an endline comment.

Procedure overview comments should probably follow the style of RnRS documens, so to just add comments to your procedure as-is, would look something like

;;; Procedure: display-n NUM ...
;; Output each argument to the screen in the order they are provided.
(define 
  display-n (lambda nums
              (letrec ((display-n-inner (lambda (nums)
                                          (display (car nums))
                                          (if (not (equal? (cdr nums) '()))
                                              (display-n-inner (cdr nums))))))
                (display-n-inner nums))))

N.B. I don’t use three semicolons for the whole procedure description, since it screws up fill-paragraph in Emacs.

---

Now about the code, I would ditch the whole define-variable-as-a-lambda thing. Yes, I get that this is the “purest” way to define a function, and it makes for a nice consistency with defining procedures are the results of LETs and other procedures, but there’s a reason for syntactic sugar, and it’s to make things more readable. Same for the LETREC—just use an internal DEFINE, which is the same thing but more readable.

It’s not a huge deal that DISPLAY-N-INNER’s parameter is called NUMS, since the procedure’s so short and DISPLAY-N just hands its NUMS straight to it anyways. “DISPLAY-N-INNER” is sort of a lame name, though. You would give it something with more semantic meaning, or give it a simple name like “ITER” or “LOOP”.

Now about the logic of the procedure. First, (equal? (cdr nums) '()) is silly, and is better as (null? (cdr nums)). Actually, when you are operating over an entire list, it’s best to make the base case a test of whether the list itself, and not its CDR, is empty. This way the procedure won’t error if you pass it no arguments (unless you want it to do that, but I think it makes more sense for DISPLAY-N to do nothing if it gets nothing). Furthermore, you should test whether to stop the procedure, not whether to continue:

(define (display-n . nums)
  (define (iter nums)
    (if (null? nums)
        #t  ; It doesn't matter what it returns.
        (begin (display (car nums))
               (iter (cdr nums)))))
  (iter nums))

But for all that, I would say the the procedure itself is not the best way to accomplish the task it does, since it is too concerned with the details of traversing a list. Instead you would use the more abstract FOR-EACH method to do the work.

(define (display-n . nums)
  (for-each display nums))

This way, instead of a reader of the procedure getting mired in the details of CARs and CDRs, he can just understand that FOR-EACH will DISPLAY each element of NUMS.