comment-style


There are typically three types of comments used in Scheme code, distinguished by the level to which they are indented and the number of semicolons that prefix them: top-level (three-semi), code (two-semi), and margin (one-semi) comments.

Top-level (three-semi) comments

Top-level comments occur at the top level. They begin with three semicolons with no indentation. The scope of their content is usually general matters about the program or the following top-level program forms. They may also be used as documentation of the interface. Headings may also be considered top-level comments, though they are typically marked with more than three semicolons.

 ;;;;;; This is a contrived module.    -*- Mode: Scheme -*- 
  
 ;;; This code is in the public domain. 
  
 ;;; This example is one of top-level comments. 
 ;;; Frobbotz gargle blatz. 
  
 ;;; This procedure adds one to its argument and returns it. 
  
 (define (mumblork x) (+ x 1)) 

Code (two-semi) comments

Code comments are used for commenting on the code itself, to demarcate mysterious sections, refactoring candidates, et cetera. They are indented to the same level as the code they comment and have two semi-colons.

 (define (that-voodoo some stuff here) 
   ;; Notice the deep voodoo here. 
   (invoke-voodo 
    (watch-out-for zombies 
                   ;; Mumble frotz!!  I need to rewrite this. 
                   garglemumph))) 

Margin (one-semi) Comments

Margin comments are to explain what a particular token or line represents. They begin with one semicolon, which is indented either to the token they refer to or some point far to the right of the line, often forty columns.

               ; a procedure that modifies something 
 (define (look mutator) 
   ...) 
  
 (define (factorial n) 
   (if (= n 0)                           ; This could also be (< N 2). 
       1                                 ; Base case 
       (* n (factorial (- n 1)))))       ; Recursive case 

Other, less common conventions

There are, of course, other conventions for comments that some people use. These are not nearly as common as the above, but they still exist:

;++ Yuck!

denotes that the following code should be refactored or otherwise reconsidered in some way later (can be used at the top level, next to code, or in a margin);

;** Very important notice!

denotes a very important comment to which special attention should be paid (like ;++, usable anywhere); and

;+++

denotes a small optimization hack (usually in the margin).


category-learning-scheme

Originally adapted from a post on comp.lang.scheme by Ray Dillinger