RFC revised

------=_NextPart_000_01FA_01BFFE11.E50607A0
Content-Type: text/plain;
	charset="iso-8859-1"
Content-Transfer-Encoding: quoted-printable

=3Dhead1 TITLE

Multiline Comments for Perl.

=3Dhead1 VERSION

  Maintainer: Michael J. Mathews <[email protected]>
  Date: 04 Aug 2000
  Version: 2
  Mailing List: [email protected]
  Number: 5

=3Dhead1 ABSTRACT

Unlike many programming languages Perl does not currently implement true
multiline comments. This can be confusing/tedious to programmers. This =
could
be solved by adding a syntax to Perl 6 that would allow for true =
multiline
comments.

=3Dhead1 DESCRIPTION

Comments are important to programmers as a way of documenting their code =
and
for debugging purposes. While it is true to add formatted documentation =
to
perl using POD tags, this can be overkill if a programmer simply wishes =
to
add lines of information here and there that are not intended to be =
public.
In fact crafty programmers can even simulate multiline comments using =
POD
tags, but this seems like a misuse of a feature intended for another
purpose, and can interfere with real PODs in a script.

=3Dhead1 IMPLEMENTATION

Perl currently allows for sigle-line comments using the pound-symbol =
"#".
Any implementation of a Perl multline comment should feel similar to =
this.
However (ideally) the multline syntax would be unique enough so that it
would not conflict with older scripts using the literal "#" (in a regex =
for
example) or in any single-line comment of arbitrary text.

=3Dhead2 Nesting

Since multiline comments will have a beginning and an ending it will be
possible to nest and overlap commented sections of perl. Nesting and
overlapping should be allowed and supported. In the case of nesting, the
outermost comment is enforced, in the case of overlapping the comments
should be treated as if they were joined. In the case of a single-line
comment overlapping a multiline comment, the multiline would end the
sigle-line comment and would in all other ways take precedence.

=3Dhead1 Comments

=3Dhead2 General reaction

The commenters on the language-list can be classed into three general
reactions: 1) those that thought multiline comments were not needed, 2)
those that thought they should be implemented as a function, 3) those =
that
felt we needed a new syntax entirely. No one, however commented that =
they
liked the original proposed implementation of using the C<(#...#)> =
syntax.

=3Dhead2 Is it needed?

Many in the community suggested that there are already adequate features =
in
the language to fulfill the requirements that multiline comments are =
meant
to address. The most frequent example cited was POD while others =
suggested
that many single-line comments should be used.

=3Dhead2 The response...

It was stated by others that using POD as a commenting mechanism had
problems, including: 1) it doesn't allow the programmer to distinguish =
their
comments from actual inline documentation; 2) it allows (requires?)
non-standard usage -- since programmers can label the comment/POD =
anything
they wish; 3) it cannot be nested since C<=3Dcut> closes I<all> =
previously
opened POD sections, and would therefore require the programmer to =
remove
any C<=3Dcut> tags within a section that she wished to be comment.

=3Dhead2 A comment function:

Many who responded stated that if it were to be added that it would best =
be
added to an existing perl feature, or made to work just like one. The =
most
frequently suggested of these was a version of qq() which would return
empty/undefined.

=3Dhead2 The response...

It was pointed out that using a function as a commenting mechanism =
suffers
two problems: 1) it means that the argument delimiter cannot appear in =
the
commented string (tricky when commenting large sections of possibly =
buggy
code); and 2) it doesnt "stand out" from the rest of the code as a =
comment
should.

=3Dhead2 Keep it perlish

Other suggestions were to utilize an more perl (or perlish) syntax to
accomplish the goal. One promising suggestion was a variation on the
here-documentation syntax which would return empty/undefined.

 #<<TOKEN;
 comments
 TOKEN

=3Dhead1 REFERENCES




------=_NextPart_000_01FA_01BFFE11.E50607A0--