Embedded comments

Embedded comments in Perl 6 are comments that use the syntax of multi-line comments, but are placed inside the main code. Unlike the one-line comments, embedded comments are not propagated until the end of the line and may be terminated by the closing character.

Let's demonstrate an example of an embedded comment on the add function, shown as follows:

sub add($x, $y) {
    return $x + #`(this is numeric addition) $y;
}

The #`(this is numeric addition) comment informs the reader that the + operator expects its operands (variables $x and $y in the example) to be numeric values (unlike the concatenation of strings, for example). The whole comment is embedded into the $x + $y expression. After the comment ends, the regular code flow continues. The compiler ignores the comment and, thus, the line remains syntactically correct.

Embedded comments should be as short as possible to make the whole code easier to read. Use it to give small explanations or to temporarily disable a fragment of code during the debugging of the program.