General approach

Comments are used to mark parts of source code files as sections that are not processed when determining or defining the functionality or structure of the program. The compiler does not usually check for syntax correctness inside comments, and does not process contents of comments also in any other way, aside from simply recording all the characters in them. Comments are frequently used by programmers to either place helpful "additional information" alongside regular code to explain the functionality of the code (as notes to themselves or other programmers), or to temporarily block out parts of the code. For whatever purpose the comments are used, they will be ignored by the compiler in terms of determining the functionality and structure of the program. Unlike many compilers for other programming languages, however, Sling comments are not completely discarded by the compiler upon parsing, and may be kept and processed alongside the code otherwise.

Sling supports both single-line and multi-line comments, and follows the same markup as is common with all languages in the C syntax family:

1. A single-line comment starts with two consecutive slash characters and spans until the end of that line (specifically until the next newline character that follows the two consecutive slash characters). Notably, the newline will not be considered as part of the text of the comment itself.

2. A multi-line comment starts with a slash character that is immediately followed by an asterisk ("/*"), and spans until the next instance of an asterisk character that is immediately followed by a slash character ("*/"). All characters in between those two character sequences (including any number of newline characters) are considered to be part of the comment text.

An example of this syntax is given below:

// This is a single line comment. Everything until the end of line will be part of the comment.

var n = 100 // A single line comment does not have to start from the beginning of the line

/* A multi-line comment starts with the slash-asterisk pair.
   It spans multiple lines, until a closing asterisk-slash pair is encountered.
   Everything in the middle will be considered to be part of the comment. */

/*
// Programmers often comment out blocks of code temporarily when testing or looking
// for the right way to develop a program. If you do this, make sure to clean up your
// code from these comments afterwards.
// This class is ignored because it is inside a comment block.
class CommentedOutClass
{
	func method
	{
	}
}
*/

FIXME comments

As mentioned, the SAM compiler does not fully discard comments, but does some amount of interpretation on them. Particularly, if a comment starts with the letters "FIXME", the compiler records the comment as a "task" that can be displayed and tracked (see the "tracker" feature of the SAM compiler).

See an example. The FIXME comment in the below program can be tracked by the compiler or other development tools.

func doSomething
{
	var n = 10
	// FIXME: Should set the value to 20
}

Documentation strings

In addition to comments, Sling has the concept of a "documentation string", which should not be used to comment out code or to insert random ramblings in the code, but to provide API or other technical documentation related to the code. Particularly, when inserting documentation strings before notable code elements, such as classes, variables or methods, automated code documentation tools will be able to include the documentation strings in resulting API documentation, for example.

Documentation strings are composed of multiple consecutive lines that start with a double-asterisk sequence. A documentation string block should start and end with a line that contains only the double-asterisk sequence. The actual documentation text would then go in between those two lines. These lines should be indented in accordance to their general position in the code. See below for an example:

**
** This is a sample class. It does nothing,
** but serves as a very good sample.
**

class SampleClass
{
	**
	** This is a sample method. It
	** also does nothing much.
	**

	func doSomething
	{
		PRINT "Something"
	}
}