Syntax:

/* C-style */

or

// C++ style

General:  
Comments are sections of a script that the compiler ignores.  The mark of good programming is well commented code.  This allows other people to understand what you have done (because you've explained it in your comments), and more importantly it allows you to understand what you've done!

There are two ways to let the compiler know that it should ignore text: C-style comments and C++-style comments.

C-style comments enclose the text in the following "token-pairs": /* and */.  Anything between /* and */ will be ignored by the compiler. The comment can extend over several lines like so:

/*
This
is
ignored
*/

C++-style comments use the // token.  Anything that comes after this token until the end of the line is ignored.  Unlike the C-style comments these only work on one line:

// This
// is
// ignored

// This
is not
//
 

You will probably use the C++ style comments most often.  But large multi-line comments will probably be best handled with C-style comments.  Here are a few style suggestions:

/************************************************************
* Use this at the beginning of a script to list information
* about it such as who wrote it, what it does, what other
* scripts it depends on, copyright information,
* revision history etc.
*************************************************************/

 Use one of the following before a function to make it stand out and to label it clearly:

/*
 * FunctionName
 */

///////////////////
// FunctionName
///////////////////

When you need to add brief information about lines of code use the following:

double theta = 0.0; // angle between v1 and v2

if( i == 0 )
    i = epsilon;    // avoid divide by 0

Don't code sloppy, be consistent in your choice of comment style, keep things aligned and comment, comment, comment!

Another use for comments is for debugging purposes.  If a function is having problems and you're not sure where the problems are coming from; you can selectively "comment out" sections of code to make the compiler ignore them.  This is much preferable to deleting the code then typing it in later.  It is also slightly preferable to cutting and pasting it to another file. For example:

int junk()
{
    double dbl = someFunc();
    // dbl = anotherFunc( dbl );
    return( dbl );
}

This example removed the line dbl = anotherFunc( dbl ); from the function.  It's really easy to un-comment it to restore the function to it's original state and it provides a record of sorts for changes made to the function (though if you're sure you're never going to use the line again you should remove it).

Here's something that will really mess you up ( and this is why you should prefer C++ style comments to C-style most of the time).

/*
void trash()
{
    double theta = 0.0    /* angle between v1 and v2 */
    // do something
}
*/

At first glance it would appear that we have commented out the whole function (which is what we want to do).  But in reality we've only commented out half of it and our script will fail to compile.  The reason for the problem is that the C-style comments comment everything out between /* and the next occurrence of */.  In the example above the next occurrence is at the end of the comment describing 'theta'.  Everything after that point is not commented, which is bad, and worse yet the final */ token-pair is "un-matched" and thus an error.

If our comment for 'theta' was a C++ style comment then we could successfully comment out the whole function with a C-style comment, which is a lot easier than adding a // before every line.