Commenting Topics

The following is some discussion on commenting in general and commenting in Lisp in particular. I've also put together a short discussion on what is a Lisp Comment? . The topics discussed are:

To Comment or Not to Comment ...

I have encountered three camps of "how to comment code".

Camp 1. I'll add the comments when I'm done.

The first camp can be characterized with the labels of either "Comments are for sissys" and/or "I'll add the comments when I'm done". People who comment this way have one or more of the following properties
  1. feel that comments are a secondary activity.
  2. have never had to do maintenance on someone else's code. ( or their own code after it has lain "fallow" for a couple of months. )
  3. don't care about what they write, just gotta get that assignment/job done.
  4. feel that it is obvious that all the code they write is wonderously lucid the first time.
These folks are potential prime case studies of "how not to do well" in 2360.

Camp 2. The minimalist approach

This second camp can be characterized with the label of "comments are unneccessary if your code is lucid enough.". There is a sublte difference between this camp and the "comments are for sissys" folks. The claim is that if write your code so that he primary audience is the human reader of the code then comments get in the way.

What would you think if your were reading some composition and in the margins were written an explanation(s) of the text that you were reading? They would probably have to be pretty big margins. You'd be pretty annoyed wouldn't you? You'd have to ask "Why did you just say so in the first place?".

Lisp allow you to practice this approach more so than other languages. Mostly because you have wide freedom in coming up with identifier names. See Steele 2.3 Symbols for more info.

One practitioner of this approach that I know of is Brian Harvey. For a class that is roughly equivalent to 2360 that he teaches at UC Berkeley the lisp code that he hands out has NO comments in it. [ OK maybe his name and a copyright notice. And on rare occations a one or two line comment on some "hack" that necessitated by the programming environment. ] The lisp ( actually scheme ) code is accompanied with a "doc" file which explains the overall design of the solution, how to use the solution, and any functions that might be unclear.

I guess another variation of this approach would be the people who practice. Literate Programming. In Literate Programming you write the documentation and the code for some system at the same time. Examples of this are the TeX typesetting system , and Stanford GraphBase ( both written by Don Knuth. remember him from Lecture #1? ). They are both books and programs. From one source file you can generate either. It is might be considered a minimalist's approach since the program code generated has no comments in it. If there where a book describing everything you needed to know about a program why would you need comments? There is a literate programming FAQ file available.

Camp 3. The Standard approach

The standard approach is to intermix the documentation with the program. Using this approach all files begin with some description of the contains, the author, the modications and dates of modifications, and BUGS assocaited with the code in the file. Then attached to each function is some textual description of what it does, what it's inputs and outputs are, and what the know potential problems are in using it.

The is a relatively standard approach to doing this in Lisp, too. I'll talk about it in the next section.

How much to comment for 2360?

Add enough comments so that someone who knows Lisp reasonably well can read and understand your code. One means to measure what level to comment at is to think of what would you need ( or would like to know ) to know if you were told to make a modification to this code in a year or so from now.

A Standard Commenting Style

The following is a somewhat standard convention followed by a lot of Lisp Hackers. Most of the AI code I've seen follows it and I think most the GNU Emacs e-lisp code follows pretty closely too.

The style is outlined in the book "Lisp Style and Design" (by M. Miller and E. Benson ISBN 1-55558-044-0 ). Here's the extremely condensed version of chapter 5 of the book. [ Editorial comments by me appears in brackets ] 

5.3 Useful Commentary
	"...You need two types of comments in program files - overview comments
	to introduce the file, and body commentary to explain the body of the 
	code within the file."

5.3.1 Overview Comments
	
	Basically should include an overview of what the file does,
	who wrote it, what the known bugs are, and an edit history.
	[ For me GNU Emacs (ChangeLog)  and RCS (rlog ) take care of the 
	   edit history outside the file itself. But this type of stuff
	   should be at the top every file no matter what the language. ]

5.3.2 Body Commentary

    " Four Semicolons(;;;;)
	...denote a sub heading in the file...

     Three Semicolons(;;;)
	...denote a description of the succeeding function, macro, or
	variable definition...
	[I usually just most of the description into the "docstring"
	  of the function or variable.] 


     Two Semicolons(;;)
	 ...denote a description of the succeeding expression...
	
     One Semicolon(;)
	 ...denotes an in-line comment that explains a particular element
	    of the expression on that line... Brevity is important for
	    inline comments"


They then go on to explain how to decompose you functions into separate files,
how to put together compilation and load files, package files , etc.
[ as your programs become bigger this latter stuff becomes more important.
	working on a 20,000 line lisp program with several other programmers
	and where there is no preset style guide is a nightmare. I haven't
	worked on one of those yet, but I have a 5,000 line BASIC horror
	story I could tell....  :-( 

  Basically the Four Semi's allow me to skip from subsection to subsection
	rather quickly using my editor ( because they're unique )
  Differentiating between comments inside of a function and outside of
	a function is nice to have.                                      ]
Most of my code tends to follow this style. ( an example file ... don't look at the code just the format. )
Back to the Lisp Style Page.
Last modified: by Lyman S. Taylor(lyman@cc.gatech.edu)
(c) copyright Lyman S. Taylor 1995, All rights reserved