Am I over-commenting my code?

belden has asked for the wisdom of the Perl Monks concerning the following question:

I've seen past discussions on perlmonks which deal with commenting style. I realize that at some point this ends up being a personal preference with consideration for consistency and conciseness being, umm, concerns. (Alliteration mostly unintentional :)

Nonetheless, I'd like to get a few opinions from the perlmonks community about a "new" commenting style which I worked out last night. As you can guess from looking at the following snip, I was reading a man page when writing up the comments.

I ended up with what I considered a well-commented method, but looking at it now I think it might just be too durned wordy. Reactions welcome.

# NAME
#        dump_subtable() - dump a subtable
#
# SYNOPSIS
#        dump_subtable ( scheme => $SCHEME, @OPTIONS )
#
# DESCRIPTION
#        dump information from a subtable stored within invokant.
#        Initialisation via init_subtable() is performed if the
#        table described by $SCHEME is uninitialised. Returns an
#        array reference to the dumped information. (See HACKER
#        INFO, below.) $SCHEME is a Unihan.txt encoding scheme
#        descriptor, eg kBigFive or kGB0.
#
# OPTIONS
#        See EXAMPLE for an example of how to use the advanced
#        features of this method. They are:
#
#        sorter => $CODE_REF
#        sorter_args => \@ARGS_FOR_CODEREF
#
# EXAMPLES
#        # anonymous sub for sorting
#        my $sorter =
#            sub { my ($ar_sortme)= shift(@_);
#                  my ($fld)= shift(@_);
#                  my @ret = sort {
#                                   ${$a->[$fld] cmp ${$b->[$fld]}
#                                 } @$ar_sortme;
#                  \@ret
#                }; # end sorter sub
#
#         # dump and sort the table by kBigFive value
#         my $ar_sorted =
#             $table->dump_subtable( scheme => 'kBigFive',
#                                    sorter => $sorter,
#                                    sorter_args => ['1'] );
#
#         # do something useful with the dumped table
#         foreach ( @{$ar_sorted} ) {
#             print ${$_->[0]} . "\t" . ${$_->[1]} . "\n" ;
#         }
#
# BUGS
#        This isn't terribly useful on multi-key $SCHEMEs, such
#        as kDefinition or kMandarin: this is due to a limitation
#        in how the table is parsed in the constructor.
#
# HACKER INFO
#        Values stored within the array reference are arrays of scalar
#        references, i.e. 
#
#        $ar_dump = $unihan->dump_subtable ( scheme => 'kBigFive' );
#            # $ar_dump->[0] is now structured as
#            # $ar_dump->[0] = [ \$unicode_scalar, \$scheme_value ];
#
sub dump_subtable {
  my ($self)= shift(@_);
  my (%args)= @_;

  my $hr_subtable = $self->{ $args{scheme} };

  if ( not defined %$hr_subtable ) {
    my $init_ok = $self->init_subtable( %args );
    die "dump_subtable() unable to auto-init subtable ", $args{scheme}
+,"\n"
        unless $init_ok;
    $hr_subtable = $self->{ $args{scheme} };
  }

  my @dumped;
  while( my ($subtable_key, $sr_uniscalar) = each %$hr_subtable ) {
    push @dumped, [ $sr_uniscalar, \$subtable_key ];
  }

  defined $args{sorter}
    ? ref $args{sorter} eq 'CODE'
      ? return $args{sorter}->(\@dumped, @{$args{sorter_args}} )
      : do { warn "dump_subtable() - sorter arg not a coderef. " .
                  "Returning unsorted data.\n";
             return \@dumped;
           }
    : return \@dumped;
}
[download]

Please let me know: too much commenting for your taste? How well do you think the man-page style lends itself to code commenting?

post scriptum: this is part of a work-related module for parsing the Unihan.txt files; when complete, I might post the module provided my employer approves.

blyman
setenv EXINIT 'set noai ts=2'

Edit ar0n -- Added readmore tag

Comment on Am I over-commenting my code? Download Code

Replies are listed 'Best First'.
Re: Am I over-commenting my code? by particle (Vicar) on Jun 11, 2002 at 17:14 UTC
if you're going through all this trouble, why aren't you using pod? then anyone can view your docs by typing `perldoc myscript.pl` as to your question, it depends on how important the code is. i'd document the entire module with pod at the end, but others prefer it interleaved with code. and if i had seventeen similar methods in the same module, i'd certainly try to consolidate the information a little more than the example you've provided. and this wasn't in your question, but i believe good tests are worth as much as good documentation. write tests as you code, and you'll begin to see why. i've even written a set of ksh test procedures for my current client -- which has improved code quality quite a bit already. ~Particle accelerates	[reply] [d/l] [select]
(ichi) Re: Am I over-commenting my code? by ichimunki (Priest) on Jun 11, 2002 at 17:20 UTC
Where are the code comments? I see a large block of commented text that would work better as POD, but not a single comment in the code itself. I like to have this interface documentation to POD so that your module can be 'perloc Module'ed by users. Given that the code is fairly dense (although not inscrutable), you might consider a note here and there about what is going on. FWIW I like the "Code Complete" method for generating correct code comments. Outline the procedure in English (or Latin or Klingon or German). Turn all those simple English statements into comments. Then write the code that does what the English states needs to be done. If one of those English steps is too complex to be done in five to ten lines, consider repeating the process for this piece of the routine. This method has the advantage of forcing you to outline your code before writing it-- which means that problems will become apparent before you write a single line of code. It also means that meaningful comments will be right there. Well, that's my two cents, anyhoo. YMMV. :)	[reply]
Re: Am I over-commenting my code? by dws (Chancellor) on Jun 11, 2002 at 18:53 UTC
Please let me know: too much commenting for your taste? Too much. I tend to be rather minimalistic with commentary, having been burned too many times by commentary that differed from the code that it was purporting to describe. It's way to easy to invest time in writing grand commentary that people won't read anyway will diverge from the code as people extend the code, but not the commentary Code is truth. I'd rather invest time in making the code readable. One way that the tendency to overcomment lulls people into sin is with subroutine names. There's a great temptation to leave a subroutine poorly named, thinking "oh, well. we'll explain it in the commentary." Poor move. An example `# NAME # dump_subtable() - dump a subtable` [download] If the commentary merely repeats the name, the commentary is wasted. If more commentary is needed, it is a strong hint that the subroutine either needs to be renamed or refactored. Worse is when the commentary lies (usually by omission).	[reply] [d/l]
Re: Am I over-commenting my code? by FoxtrotUniform (Prior) on Jun 11, 2002 at 17:20 UTC
too much commenting for your taste? Yup. :-) The NAME section is entirely redundant; you can safely get away without telling the reader that a routine declared as `sub dump_subtable` is called "dump_subtable" and dumps a subtable. As for the rest, well, it depends. If this is an interface function, then spelling out the options, listing bugs, and providing several examples is good and useful, but should probably be POD rather than comments. If it's a utility function that doesn't get exported, then IMO you'd probably be better off with a small comment block at the top, and maybe some useful comments inline. `-- The hell with paco, vote for Erudil! /msg me if you downvote this node, please. :wq`	[reply] [d/l]
Re: Am I over-commenting my code? by metadatum (Scribe) on Jun 11, 2002 at 17:14 UTC
Turn your comments into POD style, and you can generate a man page from it....	[reply]
Re: Am I over-commenting my code? by QwertyD (Pilgrim) on Jun 11, 2002 at 22:57 UTC
In addition to the other posters' advice, you may want to put the comment inside the subroutine block, like so: `sub dump_subtable { # NAME # dump_subtable() - dump a subtable # # SYNOPSIS #etc... my ($self)= shift(@_); my (%args)= @_; #etc...` [download] This way, if you want to change the order of the subs (for organizational purposes) or to move some subs into other files (less likely since this is part of a module, but probable in other types of programs), the comments will always stay with their associated subs. This will, of course, vary to taste. How do I love -d? Let me count the ways...	[reply] [d/l]
Re: Am I over-commenting my code? by Pug (Monk) on Jun 11, 2002 at 20:26 UTC
Personally I like commenting what the function does instead of how it does it. With the example section, you might want to add to it sample input values and the output of the example input. One thing that I do is put the comments through a spell checker. But then I am a terrible speller. grin -- Mortic	[reply]
Re: Am I over-commenting my code? by atcroft (Abbot) on Jun 11, 2002 at 19:01 UTC
Commenting is always a matter of personal style mixed with a need for document the code, preferrably so that someone (or even yourself) can come back to the code 6 months or a year or longer afterwards and be able to make sense of it without too much difficulty. Good documentation is never a bad thing-just be aware that comments too far from the code it applies to can be bad, although this looks quite useful for documenting the function overall. Others, I noted, suggested converting the documentation to POD format, which would also be a good idea. (Personally, I prefer too much information if I'm having to come behind and dig thru it than too little, but that is just me.)	[reply]