What are Comments?Edit

Programming code needs to be written in a way, the compiler for a programming language understands. This so-called source-code, should be written to be easy and understandable. The Source code is self-commenting, when the variable names describe their usage and the code is formatted and written in a way, to be easy readable, so someone can understand what it is doing.

Still, this is not always sufficient. So we need a way to write regular language within source code, to explain things further. That's the reason why every programming language, and LSL is no exception, provides a method to write comments.

Icon-information-22x22A Comment is text, that is completely ignored from the compiler. They don't have any function in the executed code and it doesn't matter for the compiler, if comments exist or not. Comments are for us humans.

Best practices for commentsEdit

Comments are used for a variety of reasons:

  • Explaining better what the code does
  • Mentioning Reasons for why one method is used over another
  • To document values passed in, how functions should be used or what return values contain
  • To "comment out" a line or section of code, that should not be executed for some reason, but the coder has a reason to not remove it completely, as example when testing alternatives
  • To add several information about the author, copyrights, licenses etc.

Icon-lightbulbThe frequency of comments sometimes reflects the poor quality of code. When you feel compelled to add too many comments, consider rewriting the code to make it clearer.

No comments at all are not good, but too many comments make code less readable too. Good practices are, to avoid comments that can become too fast out-of-date as the code evolves, comments that are redundant, duplicate information as also what is clear from the code. Avoid to use fancy formatting or special characters in comments.

Syntax of CommentsEdit

In general, programming languages have a different set of comment syntax, including single-line comments, block comments, end-of-line comments and documentation comments - though the syntax for those comments is sometimes similar. LSL knows from all those the end-of-line comments in all LSL versions and viewers. Block comments are available in the Mono Engine and in newer versions of the SL viewer for the LSO Engine.

Icon-warning-22x22End-of-line (//) and single-line comments (/* */) are sometimes confused and the second term used instead of the first, but they are not the same. Older SL viewers can compile only End-of-line comments in the LSO Engine and will give a syntax error for block and single-line comments.

End-of-line CommentsEdit

End-of-line comments begin with double forward slashes (//) and end with the end of the line. It can comment out a whole line or partially, but always until the next line. To comment out multiple consecutive lines, the block comment syntax should be used instead.

Some examples of valid and invalid end-of-line comments

// This is a commented line - this whole text is ignored

llSay(PUBLIC_CHANNEL, "Kitty likes cookies.");   // another way to write a comment

//llSay(PUBLIC_CHANNEL, "Kitty likes also dogs.");  //The compiler never executes this function

///// This is a valid comment. 

//* This is a valid end-of-line comment too.

// This is a comment.   // This is still the same comment.
/ This is a syntax error.

Single-line / Trailing CommentsEdit

Those comments start with /* and end with */. They should appear intended with code, either on their own line or at the end of a line that contains code. It is possible to comment out a partial part of a line with this syntax, but this is not suggested. Like in the example following, instead of commenting out a part of code, you should prefer to comment out the whole line and write the modified code on it's own line, as it makes code easier readable and maintainable like that.

Icon-information-22x22 The syntax here described has the same syntax as block comments. The compiler itself doesn't distinguish between those comments, it is more a declarative difference used generally from professional programmers.

/* I am a comment. */

llSay(DEBUG_CHANNEL, variable);     /* I am a comment too. */

if (foo > 0) {
    return TRUE; /* Trailing comment */
} else {
    return FALSE;      /* Use indentation to make it better readable */
// Valid but not suggested usage examples:

/* I am a comment, but: */ llSay(PUBLIC_CHANNEL, "I am a valid function.");

llSay(/* PUBLIC_CHANNEL */ DEBUG_CHANNEL, "This message is shown on the debug channel, not the public.");

//Suggested syntax for the above line is:
//llSay(PUBLIC_CHANNEL, "This message is shown on the debug channel, not the public.");
llSay(DEBUG_CHANNEL, "This message is shown on the debug channel, not the public.");

/* For more then one consecutive single-line comment, */
/* you should write it as block comments instead. */

/* There are no nested comments. /* So this works. */
// Invalid usages:

llSay(PUBLIC_CHANNEL, "This is /* NOT a comment. */ It's part of the string.");

//* This is an end-of-line comment, not a single-line comment */ llSay(0, "Function never executed."); 

/* There are no nested comments. /* So this does not work. */ */

/* This is an error, because the comment is missing the closing delimiters

Block commentsEdit

Block comments are used to comment out more then one line. Before block comments was introduced for LSL, the only method was to use the end-of-line comments. Though it is still a valid syntax, professional programmers use this syntax instead to comment out blocks.

It is good coding style, to precede a block comment by a blank line to set it apart from the rest of code, though it's not required from the compiler.

When large parts of code are commented out with block comments, it is easy to get confused. It should taken care to make it clear, what is a comment and what not. See the following examples for that.

/* This is the first line
of a block comment
and this the last */

/* Block comments should be 
 * formatted like this,
 * to avoid confusion and make 
 * them more readable.

/***** I am a valid comment too.
 ***** And i like stars too much. ****/

//This is an example how block comments can confuse or introduce errors:
if (foo > 0)
    return TRUE;
{               // Syntax error!
    return FALSE;

  Icon-edit-22x22 Read comments or write a new one!