in reply to Are there any drawbacks to comments -- can they hurt the performance of Perl code?

It depends how you measure performance. You have demonstrated that there is a performance hit - writing comments takes time. Often programmer time is the largest factor in how long it takes a program to solve a problem! Even when an program is used frequently, the few microseconds that comments may contribute to slowing down compilation of the script is nothing at all compared with the minutes spent writing them.

A better question is: are mandated comment blocks beneficial? To answer that you have to consider what sort of comments are beneficial and how the time might be better used.

Comments that describe how a piece of code works in most cases don't help much - the code should tell you that with well chosen identifiers and clear construction. Unless an algorythm is particuarly esoteric, don't comment how. In particular, don't use comments to expain how Perl works. If the syntax is fussy and the result unclear, rewrite using more conventional techniques rather than comment the issue under the carpet. The code is then less likely to break when Perl's behaviour changes or the code is refactored.

Comments describing how to call an internal sub should be minimal. If you need to know then you are dealing with internals and are either creating or maintaining internal code. Internal calling conventions tend to be somewhat mutable and because of that comments are harder to keep in sync with the actual code.

Comments describing external interfaces on the other hand describe something that should be cast in stone and should throughly describe parameters and calling context. However, that material should really be in POD rather than as integral comments.

At the end of the day mandated per sub comments really don't represent great value for money. Generally the time is better spent providing specification documentation and test code. Mandated per sub documentation is not cohesive in the way that a formal specification is, and doesn't catch errors the way a test suite does.

DWIM is Perl's answer to Gödel
  • Comment on Re: Are there any drawbacks to comments -- can they hurt the performance of Perl code?

Replies are listed 'Best First'.
Re^2: Are there any drawbacks to comments -- can they hurt the performance of Perl code?
by rodion (Chaplain) on Aug 12, 2006 at 09:25 UTC
    Comments serve to communicate from the person who knows how the code works (you, now) to the person who doesn't (you, or someone else, later). They are an investment, and a big part of the trade-off is how long the code will be around, and how much you care about the time and effort of the person who will read the code (maybe you).

    Nothing beats clear and elegant organization and good names for functions and variables. Some people are skilled at that and naturally remember to do it. Some aren't and don't. Mandated function comments serve to help the latter. They are a reminder to think about how to communicate, rather than just how to do get the computer to do the job at hand. If the clarity of GrandGather's code here at PM is any indication, he probably doesn't need that. I need the extra step. Often I end up with no function comment, but I've changed the name of the function to something more informative. It's nice when what one needs to know at a glance fits well in the function name. When it doesn't, a function comment is a great help.

    Function comments can also provide an outline structure, like section headings in a book. When I'm going back to find something in "Perl Best Practices", I can find it more easily because there's a brief rule summary right below the section title. I don't have to read the whole section and the supporting arguments to be reminded what the rule is. Similarly, in 

    # Accumulate and print YTD total, recording updates to disk.

sub PrintYTD {
...
}

    [download]
    The comment helps me see what's done here, without reading the part where I set permissions on the new, updated monthly-total file, having renamed the previous file as a backup. Writing the comment may also prompt me to move writing of monthly totals somewhere else, or leave a TODO for a time when such a change can be adequately tested.

    So for me, comments make for better code, both as a prompt for thinking about how the code communicates to people, rather than the compiler, and as an outline structure.

[reply]
[d/l]

      You know what is so freaking hard about this- You do *not* know how long something is going to be around.

      Most of my perl/sh/whatever stuff start out as hacks.- Today I try to keep a clear eye for the needs that come through my desk- for thihngs that may turn out to be more then hacks later..
      When I get people telling me "there's a wrong character on the second paragraph in one thousand files in the document server" (oversimplification) the second time around, maybe that last script needs to be beefed up.

      It sometimes happens the hacks you leave behind, someone else uses them- That makes me cringe and think 'oh my Jean Paul Belmondo tell me that wasn't write_random_bits_2disk.pl '

      A better real world example is the auto sorting system we have. Files all get put into one directory, and according to funny chars, new dirs get created, etc.
      I did not anticipate this would be used not just a second time, but get inside a regular cron. It's crearly time to make sure that thing has some documentation for the next poor b85tard that comes along.

      But if I made full documentation for every hack.. then froget it. Nothing gets done. It may be be different in a working office environment (perl what? is that a mac?) from a primarily development oriented environment.

[reply]

In Section Seekers of Perl Wisdom