Raku Programming/Comments and POD

Comments

Now we've covered most of the basics of Raku programming. By no means have we covered the language in its entirety. However, we have seen the basic kinds of tools that we would need for ordinary programming tasks. There is much more to learn, many advanced tools and features that can be used to make common tasks easier, and hard tasks possible. We'll get on to some of those more advanced features in a bit, but in this chapter we want to wrap up the "Basics" section by talking a little about comments and documentation.

We mentioned previously that comments are notes in the source code that are intended to be read by the programmers and are ignored by the Raku interpreter. The most common form of comments in Raku is the single-line comment which starts with a single hash character # and extends until the end of the line:

# Calculate factorial of a number using recursion
sub factorial (Int $n) {
    return 1 if $n == 0;            # This is the base case
    return $n * factorial($n - 1);  # This is the recursive call
}

When the above is executed, all the text prefixed with a single hash character # will be ignored by the Raku interpreter.

Multi-Line Comments

While Perl doesn't provide multi-line comments, Raku does. In order to create multi-line comments in Raku, the comment must start with a single hash character, followed by a backtick, then some opening bracketing character, and end with the matching closing bracketing character:

sub factorial(Int $n) {
    #`( This function returns the factorial of a given parameter
      which must be an integer. This is an example of a recursive
      function where there is a base case to be reached through
      recursive calls.
      )
    
    return 1 if $n == 0;            # This is the base case
    return $n * factorial($n - 1);  # This is the recursive call
}

Furthermore, the content of a comment can also be embedded inline:

sub add(Int $a, Int $b) #`( two (integer) arguments must be passed! ) {
    return $a + $b;
}