develooper Front page | perl.perl6.language.mlc | Postings from August 2000

RFC revised

Thread Next
From:
Michael Mathews
Date:
August 4, 2000 09:44
Subject:
RFC revised
Message ID:
01fd01bffe33$6df2d040$af0c0a0a@ny.oxygen.com
=head1 TITLE

Multiline Comments for Perl.

=head1 VERSION

  Maintainer: Michael J. Mathews <mmathews@oxygen.com>
  Date: 04 Aug 2000
  Version: 2
  Mailing List: perl6-language-mlc@perl.org
  Number: 5

=head1 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.

=head1 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.

=head1 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.

=head2 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.

=head1 Comments

=head2 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.

=head2 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.

=head2 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<=cut> closes I<all> previously
opened POD sections, and would therefore require the programmer to remove
any C<=cut> tags within a section that she wished to be comment.

=head2 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.

=head2 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.

=head2 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

=head1 REFERENCES




Thread Next


nntp.perl.org: Perl Programming lists via nntp and http.
Comments to Ask Bjørn Hansen at ask@perl.org | Group listing | About