Comments in Scheme

Programs are intended to be read both by people and by computers. Because people understand much richer and more flexible notations than computers -- real languages, as opposed to the extremely limited pseudo-languages used to direct the execution of algorithms -- it is essential to be able to include comments in program files. Comments are intended exclusively for human readers; the computer ignores them as if they were so much blank space.

In a Scheme program, any line that begins with one or more semicolons is a comment:

; This is a comment.  DrScheme will store it along with the rest of the
; text of a program, but does not even attempt to execute any part of it.

;;; The following definition, however, is read and processed:

(define centimeters-in-an-inch 254/100)

;;; And the following expression is evaluated when this program is
;;; executed:

(* 36 centimeters-in-an-inch)

It is also possible to place a comment to the right of a definition or command. The semicolon and everything to its right (on the same line) are ignored during execution.

(define centimeters-in-a-foot
(* 12 centimeters-in-an-inch))  ; One foot equals twelve inches.

We'll use comments for several purposes in Scheme programs:

Definitions are seldom completely self-explanatory. Usually, you'll want to preface each definition with a comment explaining what you want to define and how you want to define it.

;;; The number of seconds in a day is the product of the number of hours in 
;;; a day (twenty-four), the number of minutes in each hour (sixty), and
;;; the number of seconds in each minute (also 60).

(define seconds-in-a-day (* 24 60 60))

I recommend that you write the comment before writing the actual definition. Writing the comment helps the programmer articulate and specify the idea that the definition will express. Especially when you're just starting to program, it's useful to separate this stage of clarifying your ideas from the stage in which you have to think about the syntactic structure of the programming-language notation and the idiosyncrasies of Scheme's expression-evaluator.

If the calculation that your program performs is tricky or subtle, or if it depends on some non-obvious condition that is satisfied in one particular case but usually can't be relied on, you should insert a comment to explain what's going on:

(quotient total sample-size)  ; The sample size cannot be zero, since
; at least one sample is constructed by
; the BASE-SAMPLE procedure.

Even if you are the only one who will ever read your program, your future self, trying to understand the program, may need a reminder or two. It is astonishing, incidentally, how quickly this sort of detail fades from one's memory. Write it down, even if you don't now expect to forget it.

Since it's so easy to exchange programs over the Internet, programs that you write and send to others will eventually reach people who have never heard of you. It's a good idea to include a comment at the beginning of each program identifying yourself as the author and explaining how to reach you in case the reader has questions about your program:

;;; John David Stone
;;; Department of Mathematics and Computer Science
;;; Grinnell College
;;; stone@cs.grinnell.edu

;;; created October 14, 1997
;;; revisd October 17, 1997: Added XXX

A long program usually begins with a long opening comment that explains the purpose and structure of the program and presents an overview of what is to come. Here's a real-world example:

;;; The Apache server for hypertext documents records information about its
;;; actions in two log files, access_log and error_log.  This program
;;; parses those logs and generates a summary of their contents for the
;;; benefit of the webmaster.

With comments, you can and should think of writing a program as rather like writing an essay in which you describe the problem you're trying to solve and your method of solution. The code sections fit into such an essay as exhibits showing the exact, formal algorithms that express your solution.