With 100 lines of comments to 2 lines of code, versus 100 blank lines to 2 lines of code, the commented code takes 4.3 e-5 seconds longer to load & compile. Do away with the blank lines and it takes 10e-5 seconds longer.

So, even at this ludicrously high comment to code ratio, the time taken to process the comments is maybe 6/100,000 ths of a second.

And that happens just once per run of the code.

The differences shown in the runtime of the code are so small that they are influenced by whether you move the mouse during the test or not--and in my tests usually favoured the commented code! Atmospheric temperature changing the resistance of the cpu probably has more influence on the performance than the presence of absence of comments in the code. This is where benchmarking becomes totally inadequate.

Even the 16% difference below represents a real-time difference of 1.0e-7 of a second. That's one whole tenth of a microsecond.

#! perl -slw
use strict;
use Benchmark qw[ cmpthese ];

open O, '>', 'with.pl';
print O '# a comment', ' ' x 60, for 1 .. 100;
print O 'sub with{ $_[ 0 ]++; }';
print O 'our $with++';
close O;

open O, '>', 'without.pl';
print O ' ' x 80, for 1 .. 100;
print O 'sub without{ $_[ 0 ]++; }';
print O 'our $without++';
close O;

our( $with, $without );
{
    local $^W;
    ( $with, $without ) = ( 0 ) x 2;
    cmpthese -1, {
        compile_with    => q[ do 'with.pl';    ],
        compile_without => q[ do 'without.pl'; ]
    };
    print "With:$with without:$without\n";
}

{
    ( $with, $without ) = ( 0 ) x 2;
    cmpthese -1, {
        A_call_with    => q[ with( $with );       ],
        B_call_without => q[ without( $without ); ]
    };
    print "With:$with without:$without\n";
}

{
    ( $with, $without ) = ( 0 ) x 2;
    cmpthese -1, {
        B_call_with    => q[ with( $with );       ],
        A_call_without => q[ without( $without ); ]
    };
    print "With:$with without:$without\n";
}

__END__
C:\test>junk
                  Rate compile_without    compile_with
compile_without 3046/s              --            -13%
compile_with    3507/s             15%              --
With:4863 without:4447

                    Rate B_call_without    A_call_with
B_call_without 1541400/s             --            -4%
A_call_with    1602739/s             4%             --
With:2476423 without:2258362

                    Rate A_call_without    B_call_with
A_call_without 1552179/s             --            -5%
B_call_with    1632288/s             5%             --
With:2386728 without:2124584


C:\test>junk
                  Rate compile_without    compile_with
compile_without 3001/s              --            -11%
compile_with    3368/s             12%              --
With:4863 without:4447

                    Rate B_call_without    A_call_with
B_call_without 1405856/s             --           -14%
A_call_with    1630859/s            16%             --
With:2386728 without:1996218

                    Rate A_call_without    B_call_with
A_call_without 1480385/s             --           -11%
B_call_with    1655503/s            12%             --
With:2386728 without:2142348


C:\test>junk
                  Rate compile_without    compile_with
compile_without 3023/s              --            -10%
compile_with    3365/s             11%              --
With:4863 without:4469

                    Rate B_call_without    A_call_with
B_call_without 1671100/s             --            -0%
A_call_with    1676092/s             0%             --
With:2277479 without:2250533

                    Rate A_call_without    B_call_with
A_call_without 1575095/s             --            -4%
B_call_with    1636763/s             4%             --
With:2288717 without:2124584
[download]

Unfortunately, I think there is at least *one* corner case where having comments actually do make a difference: extended regular expressions with interpolated variables with or without comments.

Mind you, you're going to have to do a lot of regular expressions before you actually start noticing this.

use Benchmark qw(:hireswallclock cmpthese);
my $bappo = 'bappo';
my $foo = "foo bar baz bippo $bappo zappo";

cmpthese( -3, {
  extended => sub {
    $foo =~ /
      $bappo
      \s+
      (zappo)
    /x;
  },
  comment => sub {
    $foo =~ /
      $bappo     # this is a comment
      \s+        # inside an extended
      (zappo)    # regular expression
    /x;
  },
  no_comment => sub { $foo =~ /$bappo\s+(zappo)/ },
} );
__END__
               Rate    comment   extended no_comment
comment    480920/s         --       -11%       -22%
extended   542294/s        13%         --       -12%
no_comment 614847/s        28%        13%         --
[download]

The reason for this is most likely because of the variable interpolation (so Perl cannot store a compiled version of the regular expression) and the fact that extended comments are actually part of the string when the regular expression is being compiled.

Of course, most regular expressions that warrant the extended format with comments, are also the more complicated ones, so in the real world, this might still be a bit worse. (I leave this as an excercise for the reader).

On the other hand, saving one hour of your coworkers time when (s)he has to look at your code, is usually worth much more, so your mileage may vary ;-)

Liz

They are utterly irrelevant when it comes to performance. They exert no additional memory pressure either. Sure, the parser has to skip past it but that's not something you're likely to be able to quantify.

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.

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.

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.

Personally, I think your code should make sense by itself, first and foremost. Name your variables, subroutines, packages, etc.. with descriptive terms. Use a name like get_current_standing() for a sub instead of standing()

If I develop close with another coder, nothing ticks me off more then shortcuts like these. Then the errors come in .. you track it down to a file named "sup_off.pl" that has no record of who made it, is a year old, and the whole namespace is a shortcut. Save the greek for hex! (Sorry.. venting.).

As for myself i sprinkle #TODOs and i work the pod as i go.. I keep stuff in cvs too... That's a million zillion times more important then commenting subroutines! Jeez, this doesn't sound like a perl oriented environment at all.. sounds more like javascript to me. Comments don't spit on perldoc, you know? Users and even the developers should not have to open the code to know how to use it.. but I'm just being a parrot here. But.. the parrot talk makes sense to me.

I think you want to do what is best- Not just what the goons tell you to do. So.. get a copy of Perl Best Practices, it will kick you in the nuts.. but it will also give you discipline and inspiration. Lastly.. IMHO, look at cpan modules, look at their documentation.. where are the comments there? I don't think pod will take much longer to write then ##.. besides.. You can use perldoc on any files with pod and you get nice formatted code on the screen. Leaves out the comments.

It turns into a hellbound rathole if you take that too far though. I use a compromise approach, which is to try to make at least the variables self-explanatory where necessary, then when the routine is built and ready for the testing phase, I ask myself what additional information a maintainer (in addition of course to the mandatory change log) might need and add in comments in a single after-pass. In such cases, avoiding comments by forcing the code to be self-explanatory would also require sordid travesties of the language to be inflicted upon it. Although, when I was a total newbie and hadn't yet learned about strict references, I didn't realise back then just how horrible it actually was to do things like <travesty>:

{ no strict; return _xyz_must_have_failed_; }
[download]

</travesty> instead of simply

return 0; # xyz must have failed
[download]

-M

Free your mind

Comment for yourself.

Most of the hack/program/whatever you just wrote will be erased from "short term" memory soon. In 6 months (a round figure, but pretty good) you will have FORGOTTEN that "special" think you now know how it works. Write the comments so YOU, the programmer, can figure it out again. Trust me! You will forget the quirks, and spend LOTS of time scratching your head.

A simple rule, and has served me well. Sometimes paragraphs are needed, sometimes a simple note. Make it so you can understand.

An exercise: look back on some of your OWN old code and see if you still understand it.

Actually that section was discussing POD, and this thread is discussing inline comments. I agree with moving POD to the __END__ block.

# What this function does
sub foo {
    #Something worth noting
    blah();
}

__END__

...

=head2 foo()

  my $result = foo(1,2);
[download]

The section of Best Practices that was mentioned is as follows:
Having decided to keep the documentation together, the obvious question is whether to place it at the start or the end of the file.

There seems to be no particular reason to place it at the beginning. Anyone who is looking at the source is presumably most interested in the code itself, and will appreciate seeing it immediately when they open the file, rather than having to wade though several hundred lines of user documentation first. Moreover, the compiler is able to do a slightly more efficient job it if doesn't have to skip POD sections before it finds any code to compile.

So place your POD at the end of the file, preferably after the _ _END_ _ marker so that the compiler doesn't have to look at it at all. Or, if you're using a _ _DATA_ _ section in your implementation, wrap the documentation in =pod/=cut directives and place it just before the _ _DATA_ _ marker.