in reply to No Comment

Hello, my name is Nkuvu, and I'm addicted to comments...

I'm a prolific commenter, particularly in Perl. But I also know that I have to maintain the comments (usually) more often than the code itself. And it should also be noted that the people who are reviewing my code aren't Perl proficient. So I comment Perl-specific operations, to help the reviewer see what I am doing -- why is usually obvious (but documented if not). For example, if I have ($foo) = $bar =~ s!\\!/!g; I'll comment on it. Because you don't see things like this in C/C++.

It was also hammered into me throughout my university career that comments are good, lack of comments is bad. Period, no flexibility in that conclusion. But I can see all of the points that other monks have made, and resolve to comment less in the future. Most of my code is very similar to C/C++, due to the people I'm working with. And I can't assume that the person who maintains my code will be a Perl programmer.

When I started with Perl, it was to update a script written by a no-longer-present programmer. He had very poor style, with variable names like $l (that's an ell) and $x throughout the script. I could have killed for comments in his code, especially since I didn't know Perl. So I've kind of overcompensated since then.

I suppose I shouldn't admit that one of my scripts (which has a complicated algorithm) is over 50% comments...

Replies are listed 'Best First'.
Re: Re: No Comment
by autarch (Hermit) on Apr 23, 2003 at 17:46 UTC

    It sounds like you think comments are there to benefit people who are new to programming, or at least new to Perl. The problem is that these types of comments are incredibly distracting once you actually know the language, and at that point they just take up valuable screen real estate that could be filled with code. In most development situations, you should assume that the next person to read the code will be reasonably competent. If not, they have bigger problems than just dealing with your program

[reply]
      I disagree - I comment heavily on what I was thinking at the time. It has little to do with the actual code, and more to do with intentions: 
      # we know this is coming from XXX because of sub xxx, so we don't need
+ an extra taint check here

      [download]
      etc. I can go back to code I wrote only a week ago that I've already forgotten (small buffer :) and have trouble going through it quickly unless I do this.

      But then. maybe I'm just dopey :)

      .02

      cLive ;-)

[reply]
[d/l]

        No, you don't disagree, at least not with me ;) I think your example is an excellent example of a useful comment, because it's about the why of the code, not the what.

[reply]
        A good trail of thought, but will the comment still apply if sub xxx is changed 6 months down the road by someone else? I prefer to describe this kind of thing with assertions instead - "executable comments", as schwern calls them in the description bit for Carp::Assert. This has the added benefit of making sure that changes that disturb such dependencies and implied relations don't slip by.

        Makeshifts last the longest.

[reply]

      To tell the truth, I never really considered why I should add comments. It was just drilled into my head that I should.

      And once I start thinking about why I should comment things, I can see that I've been going about it all wrong.

[reply]

In Section Meditations