Multiline comments

Although one-line comments may be used to provide big chunks of documentation, having to place the # character in each line makes the comments themselves difficult to maintain. For example, if you modify the text of a comment, you may also want to reflow the whole paragraph so that all the lines are more or less the same length and the whole comment is more attractive visually.

In Perl 6, multi-line comments are supported. The syntax for a multi-line comment is the following. It starts with the #` sequence (the # character, same as in one-line comments, followed by a backtick symbol). Then, the part with the body of the comment goes in. It must be enclosed into a pair of brackets.

For example, curly braces may be used like this:

#`{This program in Perl 6
prints the 'Hello, World!' string}

say 'Hello, World!';

Here, the comment resides in two lines of the source code, but there is no need to mark every line of it with the # character.

Other pairs of embracing characters may be used. For example, parentheses or square brackets:

#`(A multi-line comment
placed between pair of parentheses)

#`[Another multi-line comment,
this time in square brackets]

Although the comments are intended to be read by humans in the first place, the compiler has to understand where the comment starts and ends. In the preceding example, the closing character of the comment body is defined by the corresponding character after the #` sequence.

If it is an opening brace ({), then the compiler scans the following text and looks for the closing counterpart, the } character in this example. This also means that you cannot use the closing brace in the text of the comment, because it will be treated as the end of comment.

One of the ways to have such a character in the comment is using a different pair of enclosing symbols. For example, if the whole comment is embedded in a pair of parentheses, then it is safe to use a closing square bracket in the body of that comment, as shown here:

#`(A multi-line comment
in parentheses and it contains the } character inside 
it)

Also, it will not be a problem if you use the balanced pairs of the same characters. For example, consider the following block of code:

#`(Function add(x, y) adds two numbers
and returns their sum)
sub add($x, $y) {
    return $x + $y;
}

Here, the comment is using the #`(…) pair of parentheses, but it contains another pair of parentheses inside: add(x, y). In this case, the program is correct and the comment ends where it should end according to the intention of the programmer.

The second way of allowing the same characters in the comment is to use a sequence of more than one character to mark the comment.

For example, a pair of double braces will work like this:

#`{{Two characters at the beginning
let us easily include the closing } brace, for 
example}}

Another good option is to use a combination of different characters. The closing sequence should mirror the opening one, as shown here:

#`([Another way of having  
a closing ] character inside the comment])

Finally, one-line comments may appear inside the multi-line comment. In this case, they will be just a part of it, as shown in the following example:

#`{If you want to print the value of the variable $x,
find the following line in the code:
# say $x
and uncomment it.}