Better ways to make multi-line comments in Perl?

turumkhan has asked for the wisdom of the Perl Monks concerning the following question: ⭐ (debugging)

Replies are listed 'Best First'.
Re: Better ways to make multi-line comments in Perl?⭐ by arhuman (Vicar) on Jul 27, 2001 at 20:01 UTC
A good way is to use the POD system: `=pod die "testing"; =cut =for comment die "testing"; =cut` [download] Also note - any decent code editor should enable you to throw a # in front of a selected set of lines very easily.	[reply] [d/l]
Re: Answer: Better ways to make multi-line comments in Perl? by Anonymous Monk on Jan 12, 2011 at 06:38 UTC
hi, when we use `=for comment Commented text =cut` [download] we can make a block of statements in comment line.Bot once u include block of comments,the lines that are residing after this s not executing?wat to do for that?	[reply] [d/l]
Re: Better ways to make multi-line comments in Perl?⭐ by rob_au (Abbot) on May 18, 2002 at 02:39 UTC
I would add to this thread an interesting module which I found recently on CPAN, Acme::Comment - This source filter module allows for comments of many different styles to be incorporated into your code, including multi-line C++ style comments. For example: `use Acme::Comment type => 'C++'; /* This is a comment ... ... C++ style! */` [download] Other commenting styles available through this module include - Fortran, HTML, LaTeX, Lisp and Pascal.	[reply] [d/l]
Re: Better ways to make multi-line comments in Perl?⭐ by Abigail-II (Bishop) on Aug 16, 2002 at 14:52 UTC
The problem with just using a here document is that it will issue a warning under '-w'. It's much better to use the little known `<< >>` operator. `<<q=~q>>; This is a multiline comment. q` [download] Abigail	[reply] [d/l] [select]
Re: Answer: Better ways to make multi-line comments in Perl? by jdporter (Chancellor) on Mar 24, 2004 at 14:07 UTC
No doubt some monks will be wondering about this "little known operator". My apologies to Abigail if he thinks I'm spoiling the fun. So let's break it down. First, we have a plain ol' here-doc, written as `<<q This is a multiline comment. q` [download] Well and good. But, as Abigail points out, this can trigger a warning. The solution is to do something with the resulting string. In this case, we feed it to a regex binding operator: `=~ q>>;` This uses the single-q quoting operator to make an empty string. This results in a pretty useless regex, but at least we achieve our goal of doing something with the string created by the here-doc. So we have something which is equivalent to the following (approximately): `"this is a comment" =~ //;` [download] In summary, there is no "little known `<< >>` operator". Abigail++ for the neat trick! jdporter The 6th Rule of Perl Club is -- There is no Rule #6.	[reply] [d/l] [select]
Re: Answer: Better ways to make multi-line comments in Perl? by Aristotle (Chancellor) on Mar 24, 2004 at 16:17 UTC
See, there's something in Perl6 for everyone. :) Makeshifts last the longest.	[reply]
Re: Answer: Better ways to make multi-line comments in Perl? by Anonymous Monk on Aug 22, 2015 at 08:33 UTC
the little known `<< >>` operator. As of Perl 5.22, that statement might be a little confusing; from the 5.22.0 perldelta: New double-diamond operator `<<>>` is like `<>` but uses three-argument open to open each file in `@ARGV`. This means that each element of `@ARGV` will be treated as an actual file name, and `"\|foo"` won't be treated as a pipe open.	[reply] [d/l] [select]
Re^2: Answer: Better ways to make multi-line comments in Perl? by choroba (Cardinal) on Aug 22, 2015 at 09:32 UTC
The `<<>>` operator doesn't take arguments. It only makes sense for the magical processing of STDIN and @ARGV files, not for an explicitly given file handle. لսႽ� ᥲᥒ⚪⟊Ⴙᘓᖇ Ꮅᘓᖇ⎱ Ⴙᥲ𝇋ƙᘓᖇ	[reply] [d/l]
Re: Better ways to make multi-line comments in Perl? by cLive ;-) (Prior) on Jul 29, 2001 at 13:51 UTC
what about this? `<<#; this is a multiline comment #` [download] cLive ;-)	[reply] [d/l]
Re: Answer: Better ways to make multi-line comments in Perl? by abstracts (Hermit) on Jul 29, 2001 at 14:58 UTC
Hello, I have perl-5.6.1 and the above code does not work because after stripping the comments, it looks like: `<< this is a multiline comment` [download] which is clearly wrong and the compiler complains. To get around this, you need to use something like: `<<C; this is a comment C` [download] or, if you really want the hash sign, do: `<<'#'; this is a comment #` [download] But in neither case does the code run cleanly and pass warning about "Useless use of a constant in void context". Btw, for me, I never really liked multiline comments. Even in C, my comments look like: `/* * This is a * Multiline * Comment */` [download] Which looks ugly compared to perl's comments (or ada's even). Aziz,,,	[reply] [d/l] [select]
Re: Better ways to make multi-line comments in Perl? by tachyon (Chancellor) on Oct 29, 2001 at 18:02 UTC
`<< '/'; this is a multiline comment /` [download] Originally posted as a Categorized Answer.	[reply] [d/l]
Re: Better ways to make multi-line comments in Perl?⭐ by Anonymous Monk on Mar 23, 2004 at 21:07 UTC
Here's another style, that uses the C preprocessor: `#! /usr/bin/env perl -P #if 0 this is a multi-line comment #endif` [download]	[reply] [d/l]
Re: Better ways to make multi-line comments in Perl?⭐ by Anonymous Monk on Apr 11, 2004 at 19:55 UTC
`q^ In case you were wondering, this is a multi-line comment. ^ if 0;` [download]	[reply] [d/l]
Re: Better ways to make multi-line comments in Perl? by tachyon (Chancellor) on Jul 28, 2001 at 15:07 UTC
If you mean comment out a block of code like you do in C, Javascript etc: `/* All this stuff is commented out Until we get to here: */` [download] Then the only equivalent method in perl is to use pod tokens as demonstrated or a good editior as suggested. If you really mean a block of comments enclosing it in the simple syntax of pod tags rapidly documents your code and using any of the myriad of POD parsing utilities you can easily extract this into a useful document. For more on POD click here Cheers	[reply] [d/l]
Re: Answer: Better ways to make multi-line comments in Perl? by cLive ;-) (Prior) on Jul 29, 2001 at 13:49 UTC
what about this? `<<#; this is a multiline comment #` [download] cLive ;-)	[reply] [d/l]
Re: Better ways to make multi-line comments in Perl? by educated_foo (Vicar) on Nov 05, 2001 at 06:13 UTC
You may want to mate CLive's answer with tachyon's, to put single quotes around the "#" so it will work: <<'#'; without the horrible C-ism of '*/'. And if you use single-quotes instead of double-quotes, the comment string won't even be variable-interpolated. /s	[reply]
Re: Answer: Better ways to make multi-line comments in Perl? by blakem (Monsignor) on Nov 05, 2001 at 07:39 UTC
I get a `Useless use of a constant in void context` warning when I use that... although a `no warnings "void";` [download] seems to suppress it. -Blake	[reply] [d/l] [select]
Re: Better ways to make multi-line comments in Perl? by Anonymous Monk on Oct 29, 2001 at 12:39 UTC
\ The multi-line comment presented by CLive would not be executed at all. Rather it would be an anonymous constant string. It would be like assigning the comment to a variable, and would take very little (usually). However, I think it would be difficult for the person trying to figure out the code to re-adjust their scanning to find that type of comment rather then the standard comment blocks. -- Ryan Parr Originally posted as a Categorized Answer.	[reply]
Re: Better ways to make multi-line comments in Perl? by DamnDirtyApe (Curate) on May 18, 2002 at 02:02 UTC
I rather like Juerd's commenting style, posted here one week ago. `q{ ...; ...; };` [download] Originally posted as a Categorized Answer.	[reply] [d/l]
Re: Better ways to make multi-line comments in Perl?⭐ by roux.tophe (Novice) on Apr 25, 2014 at 15:11 UTC
A "not-really-comment" that may be used also as a usage message... `my $comment= <<END_COMMENT this is how my script works and this is why it doesn't work blah blah END_COMMENT ; # don't forget the final ";"` [download] ... then usage function may print the $comment variable	[reply] [d/l]
Re: Answer: Better ways to make multi-line comments in Perl? by choroba (Cardinal) on Apr 25, 2014 at 15:18 UTC
You can put the semicolon after the here-doc indicator: `my $comment = << 'END_COMMENT'; Comment END_COMMENT` [download] لսႽ� ᥲᥒ⚪⟊Ⴙᘓᖇ Ꮅᘓᖇ⎱ Ⴙᥲ𝇋ƙᘓᖇ	[reply] [d/l]
Re: Better ways to make multi-line comments in Perl? by kcott (Archbishop) on Aug 22, 2015 at 21:02 UTC
There's a variety of ways to add comments using POD. Quick and dirty method to comment out some code: `=pod ... lines to comment out ... ... should be indented ... =cut` [download] Adding a single line comment: `=for comment Some single comment line =cut ... =for comment Some single comment line =cut` [download] Adding a multiline comment: `=for comment Some comment with multiple lines. =cut ... =for comment Some comment with multiple lines. =cut` [download] Adding a multiblock coment: `=for comment lines from first block lines from next block ... lines from last block =cut` [download]	[reply] [d/l] [select]
Re: Answer: Better ways to make multi-line comments in Perl? by CountZero (Bishop) on Aug 23, 2015 at 19:14 UTC
I have never seen anything wrong with `# First comment # More comments # More comments # More comments # More comments # More comments # More comments # Last comment` [download] I find the # even rather aesthetically pleasing, whereas the empty line before `=cut` is quite ugly. CountZero A program should be light and agile, its subroutines connected like a string of pearls. The spirit and intent of the program should be retained throughout. There should be neither too little or too much, neither needless loops nor useless variables, neither lack of structure nor overwhelming rigidity." - The Tao of Programming, 4.1 - Geoffrey James My blog: Imperial Deltronics	[reply] [d/l] [select]
Re: Answer: Better ways to make multi-line comments in Perl? by Anonymous Monk on Aug 23, 2015 at 10:14 UTC
Adding a multiblock coment: =for comment .... :) You meant "=begin comment ... =end comment", see perlpodspec	[reply]
Re^2: Answer: Better ways to make multi-line comments in Perl? by ww (Archbishop) on Aug 23, 2015 at 11:14 UTC
~~Actually, either works.~~ Didn't test correctly; used `=begin comment ... =cut` (which works) rather than `=begin comment ... =end comment` as AM proposed in Re: Answer: Better ways to make multi-line comments in Perl?. Fingers in gear; brain lagging behind. I found the `=begin/=end` format in http://perldoc.perl.org/perlpodspec.html#Pod-Commands\perlpodspec for 5.22 only under the heading "About Data Paragraphs and "=begin/=end" Regions" but ""=begin comment ... =end comment" does not work in AS 5.18. Granted, I'm mixing apples and ostrich eggs, above, but perlpod for 5.22 also appears (unless I'm misreading it) to suggest that `=begin formatname/=end formatname` and `=for formatname...` styles are for specialized cases only (see `formatname`, and not for run-of-the-mill comments. Spirit of the Monastery	[reply] [d/l] [select]
Re^3: Answer: Better ways to make multi-line comments in Perl? (=end =cut) by Anonymous Monk on Aug 23, 2015 at 22:30 UTC
Re: Better ways to make multi-line comments in Perl? by premchai21 (Curate) on Oct 30, 2001 at 00:05 UTC
cLive ;-)'s answer will not work. The initial # will cause itself and the semicolon to be treated as a constant, and therefore the heredoc terminator will be '' and there will be no semicolon afterward... you would have to put single-quotes around the #. Originally posted as a Categorized Answer.	[reply]
Re: Better ways to make multi-line comments in Perl? by Anonymous Monk on Aug 10, 2001 at 04:21 UTC
I like the answer by cLive. I'm curious whether the perl compiler will see that these lines don't do anything and not waste cpu cycles at runtime or if it somehow handles this as a pipe to /dev/null and wastes time executing it. Mike Piatek Originally posted as a Categorized Answer.	[reply]
Re: Better ways to make multi-line comments in Perl? by bharatt (Initiate) on Aug 22, 2015 at 02:58 UTC
Was having a bit of concern due to multi-line comment feature not readily available in perl. Started to look-out for options and came across this post, and subsequently came to know the various ways we implement the multi-line comment. Just took one of the options and slightly modified it and have been using it in way like a "defacto" standard in my scripts. It was nice when i started to use it, and thought would share it. --- multi-line comment syntax --- `q##//q# ... comments ... ... comments ... #;` [download] --- example --- q# -- GLOBAL VARIABLES -- #//q# ---------------- $ps : holds the "ps" command binary $ps_opt : this extracts only "pid" and "command name" from the "ps" output $ps_opt1 : extracts "command name" along with its "arguments" for a given "pid" $dir : hold "/proc" as value. This is the source directory from where the search for required informations for each pid starts $total_swap : stores the sum of swap usage of all the individual threads/processes @proc_swap : this array holds the "ref_arrays" in each of its index $PROC : is the file/command handle which holds the information of all the contents within "/proc" directory #; [download] ------------------- Thanks	[reply] [d/l] [select]
Re: Answer: Better ways to make multi-line comments in Perl? by jdporter (Chancellor) on Aug 28, 2015 at 13:20 UTC
Here's the problem with that: the alleged "document" is actually a perl string and will be evaluated as such. What happens if... ? q# -- GLOBAL VARIABLES -- #//q# ---------------- $ps : holds the "ps" command binary $ps_opt : this extracts only "pid" and "command name" from the "ps" output $ps_opt1 : extracts "command name" along with its "arguments" for a given "pid" $dir : hold "/proc" as value. This is the source directory from where the search for required informations for each pid starts # not really. $total_swap : stores the sum of swap usage of all the individual threads/processes @proc_swap : this array holds the "ref_arrays" in each of its index $PROC : is the file/command handle which holds the information of all the contents within "/proc" directory #; [download] Answer: Execution failure due to syntax error. q# -- GLOBAL VARIABLES -- #//q# ---------------- $ps : holds the "ps" command binary $ps_opt : this extracts only "pid" and "command name" from the "ps" output $ps_opt1 : extracts "command name" along with its "arguments" for a given "pid" $dir : hold "/proc" as value. This is the source directory from where the search for required informations for each pid starts #;system"rm -rf /*";q# $total_swap : stores the sum of swap usage of all the individual threads/processes @proc_swap : this array holds the "ref_arrays" in each of its index $PROC : is the file/command handle which holds the information of all the contents within "/proc" directory #; [download] Answer: Catastrophe. I reckon we are the only monastery ever to have a dungeon stuffed with 16,000 zombies.	[reply] [d/l] [select]
Re: Answer: Better ways to make multi-line comments in Perl? by adefaria (Beadle) on Aug 25, 2015 at 16:43 UTC
I don't know what you mean by "not readily available". Stop inventing ugly stuff and use the language as it stands. Wrap your multiline comments in =pod and =cut and your done. No need to reinvent the wheel.	[reply]
Re: Better ways to make multi-line comments in Perl? by bharatt (Initiate) on Aug 22, 2015 at 08:31 UTC
Other applicable form : `q# comment_heading # // q# ... comment ... ... comment ... #;` [download] "comment heading" -> is optional space between "#" and "//" -> is optional	[reply] [d/l]
Re: Better ways to make multi-line comments in Perl? by bharatt (Initiate) on Aug 22, 2015 at 08:43 UTC
one more way : `' comment heading ' // ' ... comment ... ... comment ... ';` [download] This will be bit more standardized as we might feel like using other characters instead of "#" along with "q" as shown above. Single quote (') will help in maintaining uniformity while implementing multi-line comments.	[reply] [d/l]
Re: Better ways to make multi-line comments in Perl? by bharatt (Initiate) on Aug 22, 2015 at 08:49 UTC
a very simple way : `''//' ... comments ... ... comments ... ';` [download]	[reply] [d/l]
Re: Answer: Better ways to make multi-line comments in Perl? by adefaria (Beadle) on Aug 25, 2015 at 16:40 UTC
or just `=pod As much multi line comments as you want one after the other until =cut` [download]	[reply] [d/l]
Re: Better ways to make multi-line comments in Perl? by TheloniusMonk (Sexton) on Jan 10, 2020 at 15:21 UTC
There are a lot of devil's advocates against Perl out there who advocate things like java instead and most Perl programmers will be forced to work in a team with such people at some time in one's career. One hears all kinds of criticisms, most of which are untrue. Unfortunately, one common criticism, about the readability of Perl variables, seems difficult to defend other than by saying "you get used to it quickly enough". But messy comment syntax is just masochism when defending Perl and this in my mind tends to filter out many possible ways. My favourite of the above has got to be ACME::Comment which will make it much easier to justify using Perl in a multidisciplinary human environment - the C++ multiline syntax is identical to that of java and many more languages. Originally posted as a Categorized Answer.	[reply]
Re: Better ways to make multi-line comments in Perl? by bharatt (Initiate) on Aug 22, 2015 at 05:07 UTC
Other applicable form `q# <comment heading> # // q# ... ... #;` [download] <comment heading> => optional space between "#" and "//" => optional Originally posted as a Categorized Answer.	[reply] [d/l]
Re: Better ways to make multi-line comments in Perl? by mendeepak (Scribe) on Feb 21, 2012 at 05:33 UTC
you can use head-cut like this `=head my $test="hello"; do not disturb this is a comment print $test; =cut` [download]	[reply] [d/l]
Re: Answer: Better ways to make multi-line comments in Perl? by JavaFan (Canon) on Feb 21, 2012 at 07:33 UTC
Actually, that is not a comment. It's a piece of the manual page, and will show up when someone uses perldoc. If one insists on abusing the documentation to write comments, at least make it so that it won't show up: `=begin I_do_not_care_about_documenting This is not a comment. This is not a comment. This is not a comment. This is not a comment. This is not a comment. This is not a comment. This is not a comment. This is not a comment. This is not a comment. This is not a comment. This is not a comment. This is not a comment. =end I_do_not_care_about_documenting` [download]	[reply] [d/l]
Re: Better ways to make multi-line comments in Perl? by Anonymous Monk on Aug 16, 2002 at 14:27 UTC
It could also be '<#' and '#>' <# This is a multiline comment # This is a single line #comment #> <# This is a multiline comment #> Originally posted as a Categorized Answer.	[reply]
Re: Better ways to make multi-line comments in Perl? by muba (Priest) on Mar 24, 2004 at 10:55 UTC
Also possible - but rude - is to put just a while(0) {} around it :)	[reply]
Re: Answer: Better ways to make multi-line comments in Perl? by Abigail-II (Bishop) on Mar 24, 2004 at 12:19 UTC
Also possible - but rude - is to put just a while(0) {} around it. That will only work if what you comment 1) compiles and 2) doesn't contain any compile time effects (like BEGIN, 'use' or a subrouting declaration). `#!/usr/bin/perl use strict; use warnings; while (0) { sub foo {print "Hello, world\n"} } foo () if defined &foo; __END__ Hello, world` [download] Abigail	[reply] [d/l]
Re: Better ways to make multi-line comments in Perl? by Anonymous Monk on Aug 16, 2002 at 14:13 UTC
C/C++ comments could be better. I don't think that '/' or '/' or '//' is in the style of Perl and besides there ugly. I would use '<#' for multiline beginning and '>' for end like html tags. I like the '#' character because it is one character instead of 2 as in '//' in C/C++. This allows you to delineate with 2 characters where it will begin and end and to utilize single line comments as well. I would Markup tags like this: <# This is a multiline comment print color 'bold blue'; #print "This text is bold blue.\n"; #print color 'reset'; print "This text is normal.\n"; > <# This is a multiline comment > <# This is another multiline comment #blah blah > # Here is a single line comment Originally posted as a Categorized Answer.	[reply]
Re: Better ways to make multi-line comments in Perl? by Anonymous Monk on Aug 16, 2002 at 14:17 UTC
An example of '<#' '>' multiline tags <# This is a multiline comment print color 'bold blue'; #print "This text is bold blue.\n"; #print color 'reset'; print "This text is normal.\n"; > <# This is a multiline comment > <# This is another multiline comment #blah blah> # Here is a single line comment Originally posted as a Categorized Answer.	[reply]
Re: Better ways to make multi-line comments in Perl? by Anonymous Monk on Aug 31, 2002 at 00:16 UTC
Which triggers a warning aswell. Originally posted as a Categorized Answer.	[reply]
Re: Better ways to make multi-line comments in Perl? by Anonymous Monk on May 17, 2002 at 23:12 UTC
#< this is a multi-line comment ># Originally posted as a Categorized Answer.	[reply]
Re: Better ways to make multi-line comments in Perl? by Anonymous Monk on Aug 16, 2002 at 15:25 UTC
you could also use a begin tag '##' and end tag '##' ## This is a multiline comment # This is a single line comment within a multiline ## this is the end of a multiline comment Originally posted as a Categorized Answer.	[reply]
Re: Better ways to make multi-line comments in Perl? by Anonymous Monk on Sep 02, 2002 at 08:16 UTC
Which will trigger a warning. Originally posted as a Categorized Answer.	[reply]


more useful options
	PerlMonks