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
Version: 1
Mailing List: [EMAIL PROTECTED]
Number: 102
=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) see http://dev.perl.org/rfc
Discussion archives of the perl-language and perl-language-mlc lists
