Front page | perl.perl6.language.mlc |
Postings from August 2000
This and other RFCs are available on the web at http://tmtowtdi.perl.org/rfc/ =head1 TITLE Multiline Comments for Perl. =head1 VERSION Maintainer: Michael J. Mathews <mmathews@oxygen.com> Date: 04 Aug 2000 Version: 2 Mailing List: perl6-language-mlc@perl.org Number: 5 =head1 ABSTRACT Unlike many programming languages Perl does not currently implement true multiline comments. This can be confusing/tedious to programmers. This could be solved by adding a syntax to Perl 6 that would allow for true multiline comments. =head1 DESCRIPTION Comments are important to programmers as a way of documenting their code and for debugging purposes. While it is true to add formatted documentation to perl using POD tags, this can be overkill if a programmer simply wishes to add lines of information here and there that are not intended to be public. In fact crafty programmers can even simulate multiline comments using POD tags, but this seems like a misuse of a feature intended for another purpose, and can interfere with real PODs in a script. =head1 IMPLEMENTATION Perl currently allows for sigle-line comments using the pound-symbol "#". Any implementation of a Perl multline comment should feel similar to this. However (ideally) the multline syntax would be unique enough so that it would not conflict with older scripts using the literal "#" (in a regex for example) or in any single-line comment of arbitrary text. =head2 Nesting Since multiline comments will have a beginning and an ending it will be possible to nest and overlap commented sections of perl. Nesting and overlapping should be allowed and supported. In the case of nesting, the outermost comment is enforced, in the case of overlapping the comments should be treated as if they were joined. In the case of a single-line comment overlapping a multiline comment, the multiline would end the sigle-line comment and would in all other ways take precedence. =head1 Comments =head2 General reaction The commenters on the language-list can be classed into three general reactions: 1) those that thought multiline comments were not needed, 2) those that thought they should be implemented as a function, 3) those that felt we needed a new syntax entirely. No one, however commented that they liked the original proposed implementation of using the C<(#...#)> syntax. =head2 Is it needed? 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. =head2 The response... 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 C<=cut> closes I<all> previously opened POD sections, and would therefore require the programmer to remove any C<=cut> tags within a section that she wished to be comment. =head2 A comment function: 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 qq() which would return empty/undefined. =head2 The response... 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 doesnt "stand out" from the rest of the code as a comment should. =head2 Keep it perlish Other suggestions were to utilize an more perl (or perlish) syntax to accomplish the goal. One promising suggestion was a variation on the here-documentation syntax which would return empty/undefined. #<<TOKEN; comments TOKEN =head1 REFERENCES