Commenting code in Scheme

Question

I am looking at some code in Scheme from Festival and cannot seem to figure out the comments. Currently, I can see ;, ;; and ;;; used to indicate comment lines. Other sources on the web indicate that some of the above maybe ways to indicate multi-line comments. My questions are:

1. What is the difference between ;, ;; and ;;; for commenting?
2. When is one to be used over the other?
3. Is there any other, IMO saner, way to comment code in Scheme?

Answer 1

All three of the forms you mention are single-line comments. The double-semicolon may have originally arisen as a cue in Dorai Sitaram's SLaTeX typesetting package that the comment was to be typeset as ordinary text, rather than as program text.

Scheme also has multi-line comments.

In particular, it appears that R6RS, like Racket, allows the use of #| and |# to begin and end multi-line comments. Also, the utterly magnificent #; combination comments out a full s-expression. So, for instance, if you write

#;(define (terrible-function a)
    (totally-broken-code
     here))

The entire definition is considered commented-out.

Answer 2

The comment character is ; and anything following that on the line will be ignored. The difference is visual. I have often seen a single ; used if the comment is on a line with code, ;; if the comment is on a line by itself, and ;;; if it's a heading of some sort. The most important thing in commenting is likely to follow whatever conventions you see in the code you're working with.

Answer 3

MIT/GNU Scheme allows the use of ; for single-line comments and #| and |# respectively for opening and closing multiline comments. Just tested on version 10.1.10.