Comments

Programs are instructions to computers.

But programs are written by humans, and so need to be understood by humans. Why? Hard-to-understand programs are harder to fix (if they have a bug), and harder to extend (if the program's task changes). So, it is important to keep programs easily understood by humans.

One aid to comprehension is using comments. In Smojo, we have two kinds of comments:

  1. Stack comments are only used in Word definitions, to document the before/after state of the stack by that Word.
  2. Line comments can be used anywhere in your program, either to better document its behaviour or explain tricky sections of code, or to document possible problems or points for future extensions.

	
	Of course, since comments are meant for human comprehension only, they should be discarded by the computer. 
	The word 
(
starts a Stack comment, and discards anything up to and including the closing parenthesis ). Similarly, Line comments are preceded by the word
\
and discards everything up to the end of the line.

Stack Comments

Consider this program:

		: double ( n -- n ) 
		    dup +. 	
		;
		
		2.5 double . 
		
Clearly,
DOUBLE
simply doubles the top of the stack: It consumes one item on top of the stack and puts back one item. So, the appropriate stack comment is
( n -- n )
. These are commonly used symbols but any consistent set of symbols will do. Note that
(
is a word, so you need to put spaces before and after it.

Line Comments

There are no rules for using Line comments, you use them anywhere you like to document your code. Some guidelines:

The purpose of comments is to improve clarity.

Quiz

Question 1

Why are stack comments useful? Do they have any drawbacks?



Question 2

How would you stack comment the following code:

: add3  + + ;
Does you stack comment help humans understand how
ADD3
works?



Next: New Words