FAQ
Is it possible to use too many comments? I'm looking at a script I wrote and
think I may have made it less clear by trying to make it more clear.

--
Keep up with me and what I'm up to: http://theillien.blogspot.com

Search Discussions

  • Jeff Pang at May 14, 2007 at 6:42 am

    Mathew Snyder 写道:
    Is it possible to use too many comments? I'm looking at a script I wrote and
    think I may have made it less clear by trying to make it more clear.
    If you look at Spamassassin's codes,you'll find its comments are more
    than codes.One thing I'm not satisfied with in perl is that why it
    does'nt support the multi-lines comments like /*...*/ in C.
  • Dr.Ruud at May 14, 2007 at 7:54 am

    Jeff Pang schreef:

    One thing I'm not satisfied with in perl is that why it
    does'nt support the multi-lines comments like /*...*/ in C.
    The / is taken, but there are many other ways to do multiline comments.
    For one, see perldoc perlpod.

    --
    Affijn, Ruud

    "Gewoon is een tijger."
  • David Moreno Garza at May 14, 2007 at 4:12 pm

    Dr.Ruud wrote:
    The / is taken, but there are many other ways to do multiline comments.
    For one, see perldoc perlpod.
    You mean using =begin, =end? They are not exactly multiline *comments*.

    --
    David Moreno Garza <damog@ciencias.unam.mx> | http://www.damog.net/
    <URL:http://www.georgedillon.com/web/html_email_is_evil.shtml>
  • Chas Owens at May 14, 2007 at 4:42 pm

    On 5/14/07, David Moreno Garza wrote:
    Dr.Ruud wrote:
    The / is taken, but there are many other ways to do multiline comments.
    For one, see perldoc perlpod.
    You mean using =begin, =end? They are not exactly multiline *comments*.

    --
    David Moreno Garza <damog@ciencias.unam.mx> | http://www.damog.net/
    <URL:http://www.georgedillon.com/web/html_email_is_evil.shtml>


    --
    To unsubscribe, e-mail: beginners-unsubscribe@perl.org
    For additional commands, e-mail: beginners-help@perl.org
    http://learn.perl.org/

    Not that I use them myself, but the "proper" (for various values of
    proper) way to use POD for multi-line comments is

    =for comment
    Commented text
    =cut

    Yes it sucks, yes it will be fixed* in Perl 6* (or possible earlier if
    the trend of adopting Perl 6 features in Perl 5 releases continues).
    It will be a quote-like operator, so you will be able to say

    #{
    This is
    a multi-line comment
    }

    #[
    so is this
    #[ and this one is nested ]
    ]

    #{{{ multiple brackets must match on both sides }}}

    * for various definitions of fixed, there are some caveats, the
    biggest being that a # as the first character on a line is always
    considered a single line comment even if the next character is a
    bracketing character. Don't ask me why.

    * http://dev.perl.org/perl6/doc/design/syn/S02.html
  • Chas Owens at May 14, 2007 at 6:42 am

    On 5/14/07, Mathew Snyder wrote:
    Is it possible to use too many comments? I'm looking at a script I wrote and
    think I may have made it less clear by trying to make it more clear.
    Yes, it is very easy to have too many comments, especially if you are
    using them in the wrong way. The purpose of comments is to tell the
    story of why something is the way it is is, not to tell people what
    the code does. The variable and subroutine names should tell that
    story.
  • Ken Foskey at May 15, 2007 at 1:34 pm

    On Mon, 2007-05-14 at 02:16 -0400, Mathew Snyder wrote:
    Is it possible to use too many comments? I'm looking at a script I wrote and
    think I may have made it less clear by trying to make it more clear.
    Absolutely.

    Commenting in a useful clear way I believe takes years to master.
    Maintaining your own and other scripts will teach you the difference.
    Note the following bad sample

    # loop through each entry of the xyz table.
    foreach my $key (sort keys xyz) {

    It is also very important to document WITH your code. Take the above
    snippet and consider just changing the variable from non-specific to
    problem domain, eg $key to $account. It makes it clearer.

    foreach my $account (sort keys xyz) {

    Look to the code itself first, use real names and spell them in full. I
    have a production system where prefix is shortened to pfx, pref, prefx.
    It is a nightmare to maintain.

    Use paragraphing, keep lines of code that go together with a blank line
    above and below.

    something account related;

    something customer related;
    something else customer related;

    work out totals for the report;

    Generally clearer code is more important than clearer comments.

    Coding is a craft. Simple to learn the basics, years of mastery to get
    it right.

    Ken
  • Chas Owens at May 15, 2007 at 2:42 pm
    On 5/15/07, Ken Foskey wrote:
    snip
    Look to the code itself first, use real names and spell them in full. I
    have a production system where prefix is shortened to pfx, pref, prefx.
    It is a nightmare to maintain.
    snip

    The problem here is not the shortening (which can be a good thing),
    but the lack of standardization. Each organization should put
    together a style guide (preferably based on Conway's Perl Best
    Practices*) that includes common abbreviations.

    * http://www.oreilly.com/catalog/perlbp/
  • Jeff Pang at May 15, 2007 at 3:33 pm

    Ken Foskey 写道:

    Look to the code itself first, use real names and spell them in full. I
    have a production system where prefix is shortened to pfx, pref, prefx.
    It is a nightmare to maintain.
    I personally agree with this.But for most programmers whose mother
    language is not english,wrote those comments would spend much more time
    than coding time.You may say that they can write comments with their own
    languages,but doesn't like windows office,under unix environment people
    mostly couldn't write non-english words conveniently.
  • Dr.Ruud at May 15, 2007 at 7:32 pm
    Jeff,

    Your messages get treated wrongly too.

    The end up twice on the perl beginners list, with the same Message-ID,
    and have a Newsgroups: header field with the groupname twice in it, just
    like Chas's messages.

    Message-ID: <4649D090.6020300@earthlink.net>

    The diff:

    7c7
    < Received: (qmail 12545 invoked from network); 15 May 2007
    15:34:12 -0000
    ---
    Received: (qmail 11120 invoked from network); 15 May 2007
    15:33:32 -0000

    9,10c9,10
    < by lists.develooper.com with SMTP; 15 May 2007 15:34:12 -0000
    < Received: (qmail 11236 invoked by uid 225); 15 May 2007 15:34:12 -0000
    ---
    by lists.develooper.com with SMTP; 15 May 2007 15:33:32 -0000
    Received: (qmail 10965 invoked by uid 225); 15 May 2007 15:33:31 -0000
    12c12
    < Received: (qmail 11225 invoked by alias); 15 May 2007 15:34:11 -0000
    ---
    Received: (qmail 10956 invoked by alias); 15 May 2007 15:33:31 -0000
    18c18
    < by la.mx.develooper.com (qpsmtpd/0.28) with ESMTP; Tue, 15 May
    2007 08:24:52 -0700
    ---
    by la.mx.develooper.com (qpsmtpd/0.28) with ESMTP; Tue, 15 May
    2007 08:33:24 -0700

    21c21
    < b=ZlUseYiluSL6dQjukGf7x6oeK1J2LyLpdIfrvbiUfrYR8eVnoa0m+o1xO7ryVI2Q;
    ---
    b=hUCgqsnBUDoIiwKfxb35jCIsONzYpA0/SNa/iIE2nagfH0qhtrQl63Ot0fow7qFN;
    37c37
    < X-ELNK-Trace:
    7070c57df59c6c2974bf435c0eb9d4780e74e32b2412d3e602759962c1c6f405dcaa4df6
    116241b5350badd9bab72f9c350badd9bab72f9c350b
    add9bab72f9c
    ---
    X-ELNK-Trace:
    7070c57df59c6c2974bf435c0eb9d4780e74e32b2412d3e663eb761851f44a575458a107
    158c2e4b350badd9bab72f9c350badd9bab72f9c350b
    add9bab72f9c

    Again this 10 minutes difference at the start. Did
    somebody(AT)develooper.com switch on a bad type of greylisting?

    --
    Affijn, Ruud

    "Gewoon is een tijger."
  • Chas Owens at May 15, 2007 at 7:43 pm

    On 5/15/07, Dr.Ruud wrote:
    Jeff,

    Your messages get treated wrongly too.

    The end up twice on the perl beginners list, with the same Message-ID,
    and have a Newsgroups: header field with the groupname twice in it, just
    like Chas's messages.
    Right, the problem has to be at la.mx.develooper.com then. The
    chances of both Google and Earthlink screwing up in the same way is
    very unlikely.

    Ask, are you the admin?
  • Jeff Pang at May 16, 2007 at 1:45 am

    Dr.Ruud 写道:
    Jeff,

    Your messages get treated wrongly too.

    The end up twice on the perl beginners list, with the same Message-ID,
    and have a Newsgroups: header field with the groupname twice in it, just
    like Chas's messages.
    I don't know what happened.I've changed from my premium Earthlink to
    free Yahoo/GMX accounts.But seems the problems still exist.So I don't
    think there was something wrong about me.

Related Discussions

Discussion Navigation
viewthread | post
Discussion Overview
groupbeginners @
categoriesperl
postedMay 14, '07 at 6:17a
activeMay 16, '07 at 1:45a
posts12
users8
websiteperl.org

People

Translate

site design / logo © 2022 Grokbase