The difficulties of commenting code

[Henri Icarus]

In his good post yesterday, Ovid asked about rewriting a large applications and one answer that came up over and over again was "Comment the inputs and outputs of each subroutine." By this I suppose folks meant that you should put one of those nice blocks at the begining of the code with lots of little descriptive text about parameters and return values, etc..

Now I don't know about you all, but I've tried to do this and, but invariably I end up needing to add another parameter, or change the result to be a list (or a reference) so that I can pass back multiple results, and then, (call me lazy :-) I forget to update my little comment block at the begining of subroutine. So later when I go back (or heaven forbid someone else does) to look at this subroutine and I read the comments, and I look at the code, and I'm worse off than if I hadn't commented it because things don't match.

So, lately I've just been sticking to things like:

# foo: reasonably general description of what foo does
sub foo {
    my $detailed_parameter_variable_name = shift;
    my $another_detailed_parameter_variable_name = shift;
    my $return_value_ref = {}; #hash of values to return
   ...
    return $return_value_ref;
}

So the wisdom I'm looking for is what others have found to be the most effective use of commenting time and coding style to maximize "self-documenting" of the code.

-I went outside... and then I came back in!!!!

[damian1301]

If you look across some modules like CGI and some other standard ones, you will notice that they have that exact same commenting style.

I bought a C++ book recently and it stated that comments may or may not be good because people might not update them and it will confuse you later. So it is at the choice of the user. In this case, it is what happened to you.

Personally, I don't comment much. I find that it doesn't help me unless I have some really complex code. Usually I have helpful variable, subroutine, and script names that will help me along my path and most of the time my code isn't too complex anyway :).

Overall, that commenting style seems to be the best decision from what I know because you might change the order or names of variables but the functionality still remains the same so the comment will never need to be changed. Thus, preventing confusion and bad comments.

UPDATE: I just noticed Iwas a little vaque in my answer. By "That commenting style" I meant like the subroutine (s)he showed above.



$_.=($=+(6<<1));print(chr(my$a=$_));$^H=$_+$_;$_=$^H;
print chr($_-39); # Easy but its ok.

[voyager]

Agreed. And in addition to clear names for variables, (stolen from Refactoring, Fowler) replace several lines of code and the comment with a well-named sub:

sub xxx {
    # this code does foo and bar and baz
   [many lines of code]
}

can become

sub xxx {
    do_foo_and_bar_and_baz();
}

sub do_foo_and_bar_baz {
    # no explicit comment needed, since sub has clear name
    [many lines of code]
}

[eejack]

I've changed my style of commenting many times (as many times as I have changed my style of coding).

I have found that if I write clear code and use meaningful variable names comments are fairly unnecessary. This is not to say that I shouldn't comment the code anyway, because what is clear and meaningful to me may not be to someone else.

What I have found extremely handy is commenting the ends of my blocks and subroutines if they are more than a few lines apart. For me finding the ends makes life easier (and the ends normally don't change).

if ($some_id eq "somthing"){# beginning of some_id
   ... do lots of meaningful and impressive things here
   for my $i (0 .. 10){
       do something brief here
   }
} else { # else of some_id
  &a_really_descriptive_thingy;
} # end of some_id

....

sub a_really_descriptive_thingy {
     ....something fun happens here
} # end of a_really_descriptive_thingy

One thing I have stopped doing is commenting my code with poetry, jokes and completely meaningless bits.

I still get my chops busted for one comment I made in the middle of a fairly routine script.

# Reset Alien Receptor Beam!

The guy spent an hour trying to find it to reset it...:)

EEjack

[tilly]

As I say on my home node, behind the scenes the two of us were engaging in much more friendly chatter. But still the discussion at Re (tilly) 2 (disagree): Another commenting question, has a lot to say about commenting style.

As for your specific point, if a function will have many arguments, I make the arguments to the function a hash. Should I need to fundamentally change what a function that is part of a public API does, I write a new function, gut the old and make it a wrapper around the real function. Or vice versa. Plus I make my functions small and simple. If they do something simple and clear, then I find that they do not find themselves in need of great amounts of editing later.

[dthacker]

In a previous life I wrote many, many lines of Informix-4gl. Over the years I found myself migrating towards the descriptive variable/descriptive sub style of commenting. As I've started learning Perl I've found myself adding lots of one liners that explain how things work. Most experienced Perl folks would probably find these redundant, but I'm still in the baby code stage and I need the reminders. As I develop my perl instincts, I hope to eliminate the one liners and go back to descriptive variable/descriptive sub.

Dave

[pmas]

I agree - descriptive names are important, and comments far aways from actual code are seldom up-to-date: the farther away, the less likely to be updated.

Still is useful to describe usage of subroutine near sub definition and maybe relationship between parameters - common idea.

I *almost always* add one-line comments where variable is defined, something like:

sub foo {
    my $detailed_variable_name = shift;   # always some comments!!
    my $another_variable_name = shift;    # always some comments!! 
    my $return_value_ref = {};            # hash of values to return
   ...
    return $return_value_ref;
}

Lead programmer in company where I 'grow up' was very strict. He believed that programmer's freedom should not be wasted on inovative ways to invent new naming convention for each program. We used excellent editor (MultiEdit), what allowed with one click to grep all lines matching variable name under cursor (also the line where it was commented). It was good incentive to make one-line comment in the same line as my $varname = shift;

Also, I get used to write one-line comments in the same line for each procedure call (program names were in DOS, 8+3 characters, not too helpful for descriptive names. Such comments, once written, are easy to copy-paste.

pmas

To make errors is human. But to make million errors per second, you need a computer.

[andreychek]

If I may offer a humble observation -- your post here is based on code where you update parameters, but (in your words) you find yourself "too lazy" to update the comments in the subroutine.

First off -- I think you and several others are correct that nothing beats nice, descriptive variable names.. I particularly like the idea of using hashes when there are several parameters involved.

However, I also feel that commenting your API is quite important, and you can't always get every necessary detail about a parameter into it's own name.. and if you can, I think you're names will be quite long :-) I believe the Perl term for what you are doing is called "false laziness". The objective is to be lazy overall, where you have to do the least amount of work. When you are maintaining your code, as soon as you find yourself needing to dig up info on a parameter, where a comment could have saved you, I think you may be missing out on the benefits of the Perl virtues. Furthermore, while you may understand it -- you coworkers may not.. job security is nice, but just remember that one day, you'll be the one needing to learn somebody elses code :-)
-Eric

[Henri Icarus]

Good point. My lazyness probably is the false kind, because indeed it's gotten me into trouble. I never have trouble maintaining the comments inside the subroutine, it's that "header block" that gets me!

-I went outside... and then I came back in!!!!