| Note: these documents may be out of date. Do not use as reference! |
To see what is currently happening visit http://www.perl6.org/
Multiline Comments for Perl.
Maintainer: Michael J. Mathews <mmathews@oxygen.com> Date: 14 Aug 2000 Mailing List: perl6-language-mlc@perl.org Number: 5 Version: 3 Status: Frozen
Unlike many programming languages Perl does not currently implement true multiline comments. This, and the workarounds that are in common use can be problematic. This could be solved by adding a new syntax to allow for comments to span more than one line, like the variation on here-documentation cited below.
Comments are a standard and important way for programmers to make their code more understandable and therefore more maintainable. It is also a vital tool for isolating bugs in programs and for temporarily "turning off" sections of code as part of testing. Programmers who wish to include comments across many lines are currently required to start each line with an unquoted hash symbol ("#"), which removes all text until the next newline from the Perl interpreter.
For very small programs the single-line comment is sufficient. More and more however programmers are choosing Perl as the best tool for bigger projects, possibly involving thousands of lines of code. Other popular languages (like Java and C++) that were designed from the outset as being useful for large projects implement both singleline and multiline comments. Some languages like Java also have a third type of "comment" which can be used for inline documentation (the distinction being that these items are meant to be viewed separate from the actual code).
The languages mentioned above have a distinct advantage over Perl in this regard. They encourage easy and consistent multiline comments. The alternatives available to Perl programmers however are neither easy (comment each and every line of code individually, possibly with the aid of a macro they've written, or that might have been built-in to their particular text-editor), nor consistent (use some other language feature to simulate multiline comments, like POD).
The fact that so many people on the List suggested using POD (implying this is a common work-around to the lack of true multiline comments) points out how many people would like the functionality. However POD has at least three problems:
Novice Perl programmers who are more-likely-than-not to be familiar with C++ comments can learn the "#...\n" comment syntax easily enough but POD has a completely different syntax, unrelated to "#", and is often not listed in reference books as being related to comments at all (PP3 a notable exception).
POD, of course stands for "Plain Old Documentation" but most of the time comments are not intended to be included in documentation (separate from the code). This is particularly true when using comments as a debugging tool. This adds to the Not Intuitive, and Not Consistent problems mentioned here.
Even if someone did know about POD's ability to act like comments, there is no standard syntax required for POD that is specifically meant to be a comment. This leaves it up to the programmer to try any of these sorts of methods:
=begin ARBITRARYTEXT ... =end ARBITRARYTEXT =cut =ARBIRTARYTEXT ... =cut =for TRANSLATOR ... =cut
Since there is no standard, finding these types of comments in other people's code (or even your own) is made more difficult. Further there is currently no guarantee to insure that the POD you are using for comments will some day be used as part of some legitimate POD.
Perl currently allows for single-line comments using the pound-symbol "#". Any implementation of a Perl multilline comment should feel similar to this. However (ideally) the multiline syntax would be unique enough so that it would not conflict with older scripts using the singleline "#" syntax.
Since multiline comments will have a beginning and an ending it will be possible to nest and overlap commented sections of Perl. Overlapping should not be allowed however for several reasons: it will make the parsing job considerably harder, it will make the syntax more confusing. Nesting on the other hand should be simple to implement if we enforce what Glenn Linderman calls "block opacity" -- his term for the fact that anything within a comment block should be invisible to the parser, up to the end of the comment block. This implies and requires that multiline comment blocks have different and fairly unique block delimiters.
The comments from the language-list can be classed into three general
reactions: 1) those that thought multiline comments were not needed at all,
2) those that thought they should be implemented as a function, and 3) those
that felt we needed a new syntax entirely. No one, however commented that
they liked the original proposed implementation of using the (#...#)
syntax.
Many in the community suggested that there are already adequate features in the language to fulfill the requirements that multiline comments are meant to address. The most frequent example cited was POD while others suggested that many single-line comments should be used.
It was stated by others that using POD as a commenting mechanism had
problems, including: 1) it doesn't allow the programmer to distinguish their
comments from actual inline documentation; 2) it allows (requires?)
non-standard usage -- since programmers can label the comment/POD anything
they wish; 3) it cannot be nested since =cut closes all previously
opened POD sections, and would therefore require the programmer to remove
any =cut tags within a section that she wished to be comment.
Many who responded stated that if it were to be added that it would best be
added to an existing Perl feature, or made to work just like one. The most
frequently suggested of these was a version of qc() which would return
empty/undefined but not cause a warning under warn.
It was pointed out that using a function as a commenting mechanism suffers two problems: 1) it means that the argument delimiter cannot appear in the commented string (tricky when commenting large sections of possibly buggy code); and 2) it doesn't "stand out" from the rest of the code as a comment should.
Other suggestions were to utilize a Perl (or perlish) syntax to accomplish the goal. One promising suggestion was a variation on the here-documentation syntax which would return empty/undefined and not cause a warning.
#<<TOKEN; comments TOKEN
This issue was originally discusssed on perl6-language@perl.org. After creating a sublist for discussing multi-line comments (perl5-language-mlc@perl.org), there was no clear consensus on this issue after one week's discussion.
Randal L. Schwartz & Tom Christiansen www.oreilly.com "Perl comments are like (modern) shell comments. Anything from an unquoted pound sign (#) to the end of the line is a comment. There are no C-like multiline comments."
Larry Wall PERLPOD.pod (standard distribution)
Larry Wall, et al. Programming Perl (3rd. edition). pages 630 - 631, 634.
Tom Christiansen PERLSYN.pod (standard distribution)
Dr Nikolai Bezroukov www.softpanorama.org#Comments "Perl has rather inflexible and limited comments. The desire to preserve compatibility with shell languages dictated the use of #, but here Perl robbed itself of [an] important symbol (that can be used, for example for casting scalars into numeric). This differences creates problems for heavy users of C-like languages and one can write a preprocessor that permits usage of C and C++ style comments. In any case if you are C programmer you need to check you scripts for wrong comments..."