| Note: these documents may be out of date. Do not use as reference! |
To see what is currently happening visit http://www.perl6.org/
Inline Comments for Perl.
Maintainer: Glenn Linderman <glenn@linderman.com> Date: 14 Aug 2000 Last Modified: 14 Sep 2000 Mailing List: perl6-language@perl.org Number: 102 Version: 2 Status: Frozen
Unlike many programming languages Perl does not currently implement inline comments. This can be confusing/tedious to programmers. This could be solved by adding a syntax to Perl 6 that would allow for inline comments.
Comments are important to programmers as a way of documenting their code and for debugging purposes. Perl's comment syntax requires that comments can only be placed at the end of a line, or on a separate line (or lines). Sometimes it is desirable to place a comment (or comments) within a line.
Perl currently uses the "#" character as an end-of-line comment introducer (as do many other scripting languages). RFC 5 (multiline comments) suggests as a possible promising syntax an introducer of the form "#<<TOKEN", combining the perl concepts of "comment" and "here document" for multiline comments.
It is felt that an inline comment syntax should leverage the existing Perl comment concept ("#" introducer) and that the introducer and terminator should look like a matched pair for ease of understanding.
C/C++ use "/*" and "*/" as introducer/terminator for in-line and multi-line comments. A different syntax was introduced in C++ for end-of-line comments: "//".
Pascal uses "(*" and "*) as introducer/terminator for in-line and multi-line comments. It has similar difficulties as C/C++ with commenting out blocks of code.
Forth uses "(" and ")" as introducer/terminator for in-line and multi-line comments, and "\" for end-of-line comments.
Basic doesn't support in-line or multi-line comments.
All the languages that use the same syntax for in-line and multi-line comments suffer from confusion when a multi-line comment is used to comment out a block of code containing in-line comments. Implementations have historically varied within the language on how to handle that situation.
An idea that produces a paired feeling would be to use one of the paired character pairs, as in "#<" and ">#". I like this one best, of the three paired character possibilities ("<>", "()", "{}") because it is more closely related to the "#<<TOKEN" syntax suggested for multi-line comments by RFC 5, thus also achieving a more Perlish feel, when combined with that syntax.
An idea with obvious appeal to C/C++/Pascal programmers would be to use "#*" as the introducer, and "*# as the terminator. This would probably work as good as any.
Because "#" has been used to mean comment, it seems that something related to "#" should continue to be used to mean comment.
Use of a bare "#" as an in-line comment terminator would break lots of existing practice, where people have used a variant number of "#" characters to introduce comments of more or less importance, or as a way of achieving "pretty" multi-line comments (example of such next)
################################# ## This is a stand-out comment ## #################################
Hence it seems some other character should be combined with "#" as an in-line comment introducer, and used in reverse order (per practice in other languages) as the comment terminator.
Because historically there is nothing to prevent a sequence such as the following:
code #< this is an end-of-line ># comment
from appearing, this suggestion is not 100% compatible with perl5 syntax. However, such a sequence is relatively unlikely: I've never seen one in any Perl code I've perused. By limiting this construct to less than a single line, it limits the boundaries of confusion: if "#<" is found with the intended meaning of an end-of-line comment introducer followed by a "<" character, the highly probable lack of the sequence ">#" within the same line can be diagnosed with a warning or error identifying exactly the line involved.
There was some discussion of in-line comments in the perl6-language and perl6-language-mlc lists. There wasn't a consensus reached. The competing suggestion for in-line comments was to define "qc/comment/" as a syntax that evaporates. I don't like that syntax, because it looks more like code than comment, and doesn't stand out to the eye as a comment when mixed within code:
$foo = qw/foo bar/ qc/eat me/;
It is not clear whether such syntax would be easily readable within all forms of expressions, without operators, as shown in the above example, vs
$foo = qw/foo bar/ #<eat me>#;
Should be straightforward in the Perl parser/lexer.
RFC 5: Multiline Comments for Perl.
Discussion archives of the perl-language and perl-language-mlc lists