RFC 102 (v2) Inline Comments for Perl.

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