This and other RFCs are available on the web at
http://dev.perl.org/rfc/
=head1 TITLE
Inline Comments for Perl.
=head1 VERSION
Maintainer: Glenn Linderman <[EMAIL PROTECTED]>
Date: 14 Aug 2000
Last Modified: 14 Sep 2000
Mailing List: [EMAIL PROTECTED]
Number: 102
Version: 2
Status: Frozen
=head1 ABSTRACT
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.
=head1 DESCRIPTION
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.
=head2 Ideas from other languages
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.
=head2 Ideas for perl
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.
=head2 Compatibility considerations
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.
=head2 Discussion in perl6-language and perl6-language-mlc
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>#;
=head1 IMPLEMENTATION
Should be straightforward in the Perl parser/lexer.
=head1 REFERENCES
RFC 5: Multiline Comments for Perl.
Discussion archives of the perl-language and perl-language-mlc lists
