[% setvar title Inline Comments for Perl. %]

This file is part of the Perl 6 Archive

Note: these documents may be out of date. Do not use as reference!

To see what is currently happening visit http://www.perl6.org/

TITLE

Inline Comments for Perl.

VERSION

  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

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.

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.

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.

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.

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.

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>#;

IMPLEMENTATION

Should be straightforward in the Perl parser/lexer.

REFERENCES

RFC 5: Multiline Comments for Perl.

Discussion archives of the perl-language and perl-language-mlc lists