Home (Spotlight) | TOC | Products & Ordering | Technical Info | Contact Zeus

Zeus Tech Note
Using Comments

(This document last revised April 24, 1997)

Copyright © 1996-1997. Zeus Productions. All Rights Reserved.
Written by Bruce A. Epstein

Q. What is a comment and why do I care?

A comment is text within a program, script or batch file that is used to improve the readability for humans. Comments, as indicated by one or more special comment characters, are ignored by the compiler or interpreter. It is good practice to include liberal comments in your code, so that either you or someone else reading it later can make sense of it. It is not unusual to include a comment for every two to threee lines of programming, often referred to as self-documenting code.

Q. What is a comment character?

Comment characters are used to indicate that some text is a comment and should be ignored by the computer. Different languages and programs use different comment characters:

Lingo uses two hyphens (--) to indicate a comment
DOS batch files, use REM at the beginning of the line
Windows INI files use a semi-colon (;) at the beginning of the line Refer to the TechNote, "The DIRECTOR.INI and LINGO.INI" files.
Some UNIX utilities use a number sign (#) at the beginning of the line
C uses a double slash (//), or a combination of slashes and asterisks (/* */)
FORTRAN uses the letter C at the beginning of the line

Creating Comments

Some languages only allow comments to exist on separate comment lines. Others, such as Lingo also allow comments to exist at the end of a line following actual programming scripts. In most languages anything following a comment character will be ignored until the next end-of-line character (usually a CR or CR/LF combination).

For example:

-- This is a Lingo comment on its own line



set x = 1 -- This is a Lingo comment at the end of a line



-- To create a multi-line comment in Lingo,

-- begin each line with it's own

-- comment delimiter

The C language allows comments to precede actual programming on the same line, as long as the comment starts with "/*" and ends with "*/ ". C uses two forward slashes "//" to comment out an entire line.

For example:

// This is a C comment that lasts until the end of the line

x = 1; /* This is a C comment at the end of a line */ 


/* This is a multi-line comment in C that lasts until
the ending comment-delimeter is reached,d, even if
it is not until a later line */

Although unusual, you could even do this:

/* This is a C comment at the start of a line */ x = 1; 

x = /* This is a C comment in the middle of a line */ 1; 

/* This is a /* nested C comment */ which will confuse some compilers */

Comments within Director

Director offers a number of ways to comment or uncomment your code. You can:

Manually add or delete two hyphens (--) at the beginning of one or more lines of code.
Use the "Comment" and "Uncomment" buttons in the script window button bar to comment/uncomment the currently higlighted line(s) of text.
Use Command-Shift-> (greater than sign) to comment the currently higlighted line(s) of text. (This was also a menu option in Director 4)
Use Command-Shift-< (less than sign) to uncomment the currently higlighted line(s) of text. (This was also a menu option in Director 4)

Continuation Characters

Most languages (the notable exception being C) assume that each line of code is terminated by and end-of-line character, usually a CR. A continuation character is a special character used to continue the current line of a script onto the next line. This is useful for breaking up long lines of code, especially for readability.

The Lingo continuation characters is created using Option-Return on the Mac or Alt-Enter on the PC. It looks like a line bent at a right angle (unfortunately, it does not reproduce in HTML or in most programs outside of Director.)

Beware of comments which end in a continuation character. They wull cause the next line to be included in the comment.

C does not use a continuation character. A line of code continues automatically until it is terminated by a semi-colon (;). The one exception is with macro definitions. A macro is assumed to terminate on the current line unless the backslash (\) continuation character is used.

Notes:

Use comments liberally, even when you are the only programmer. They will help you immensely if you have to fix a bug six months or years later. Or they'll help the next poor slob who has to maintain your code when you take a better job.
Create comments that complement the programming code, not simply reiterate it. A comment such as "Set X to zero" is useless. Use comments that explain what the code is doing at the conceptual level, not the variable level, such as "Reset the Number of Correct Answers". Refer to the TechNote, "Programming Do's and Dont's".
Many of the characters that indicate a comment in one language, are used for something else entirely in other languages. Be sure that you understand the symbols and their usage in the specific context.
Commenting out code for test purposes is an ideal way to eliminate some code temporarily. Likewise, be sure to comment out any debugging code when your project is finalized.
Commented text is completely ignored. If you forget to uncomment some text, your program may not work as expected. This is especially true when editing the DIRECTOR.INI file. If you don't uncomment a line in the file first, any changes will have no effect. Refer to the TechNote, "The DIRECTOR.INI and LINGO.INI" files.
Comments ordinarily last only until the end of the current line, but will extend onto the next line if a continuation character is used. That is, if the first line ends with a continuation character, the second line will be "commented out", even though it does not begin with a comment character itself.