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

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 { ... }
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.

  • Comment on Re^2: Are there any drawbacks to comments -- can they hurt the performance of Perl code?
  • Download Code

Replies are listed 'Best First'.
Re^3: Are there any drawbacks to comments -- can they hurt the performance of Perl code?
by leocharre (Priest) on Aug 14, 2006 at 13:58 UTC

    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.