Knowing how to comment on and document your code is something invaluable to both beginner programmers and veterans alike. With Perl, it’s no different, especially given Perl’s relative flexibility as a language compared to other languages. You can write a super complex, single line of Perl that can effectively carry out something that would take one hundred lines in a language like C, but without documentation in your code explaining exactly what it is you did, this could potentially lose you or any other coder returning to your program a month after you wrote it.
In Perl, there are two ways to leave comments. We’ll go over both Perl comment methods in this guide, plus list some handy resources you can use to improve your coding skills with Perl, and in general. To begin, check out this introductory Perl course.
Standard Perl Comment
A standard comment in Perl is denoted with a hashtag. Any line that begins with a hashtag will be passed over by the interpreter, but you will be able to use it within your actual code to explain and determine what it is each block is actually doing.
Remember, you might think you have it down now, while you’re writing it, but a month or even a few days later, your code might look like a bunch of nonsense. It happens. You can learn the programming basics in this course and learn more tips of the trade, but remember this one piece of advice when you’re just starting out: comment your code!
- How to Comment in Perl
This is what a standard Perl comment looks like:
# This is a comment.
If you write something like this:
#!/usr/bin/perl # I'm commenting my code! print "Hello World\n";
It will produce the following:
You can also comment after a function, but remember that anything directly after a hashtag on that line will not appear in the program.
#!/usr/bin/perl # I'm commenting my code! print "Hello World\n"; # Here's another comment!
The following will, once again, produce nothing but:
Both the comments on the preceding lines and the comment after the string do not appear once the program is built. Learn more Perl basics in this introductory course.
- What is the #!/usr/bin/perl comment?
As you can see, the comment portions denoted by the hashtag is completely left out, as is the part labeled #!/usr/bin/perl. This is one of the most important comments you can write in Perl. In fact, the first line of every application you start writing in Perl should be this one:
What this does is let the shell know that the following application’s script is to be passed onto the /usr/bin/ directory, where the Perl compiler is located. Always include this comment at the start of your programs. You can check out this Perl course to learn more.
Pod, or Plain Old Documentation, is a markup language built specifically for Perl documentation purposes. This is a much more complex way to document your code within your actual script. You can even use certain applications to convert Pod into other formats like HTML, XML, or plain text.
There are three different types of paragraphs you can use in the Pod markup language. These are:
- ordinary paragraphs
- verbatim paragraphs
- command paragraphs
Each paragraph type has its own specific function and format. If you’re a newcomer to coding, you might want to stop here and check out this course on programming for non-programmers, which will shine more light on some of these concepts and make them easier to grasp once you come back again.
To document your code using the Pod language, you just need to begin your line with an equal sign. Anything between the first equal sign and the =cut will be ignored by the compiler. You can write much more extensive documentation this way without having to clutter everything up with so many hashtags.
#!/usr/bin/perl =begin comment This is a Pod comment. You can write as many lines as you want without having to specify with a hashtag at the beginning of each line. This is the end of the Pod comment. =cut print "Hello World\n";
This will ignore the huge comment and just print:
You can use a combination of both the hashtag comments and the Perl Pod comments and both will be ignored.
Perl is a complicated language to start out with. If you’re a new programmer, try a language like Java instead. You can check out this beginner’s Java course to get started.