RFC 102 (v1) 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
  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