Slash Boxes
NOTE: use Perl; is on undef hiatus. You can read content, but you can't post it. More info will be forthcoming forthcomingly.

All the Perl that's Practical to Extract and Report

The Fine Print: The following comments are owned by whoever posted them. We are not responsible for them in any way.
More | Login | Reply
Loading... please wait.
  • by jjohn (22) on 2004.12.19 16:44 (#36934) Homepage Journal

    Strangely, I agree with Graham's point. Sparse, on-point comments are wonderful. Code that's too tricksy to grok should be rewritten. From my own experience, I find that my perl vocabulary has shrunk while making the programs easier for me to pick up months later. Also, debuggers work on code, not comments. That's to say, a reader needs to grok the code not what the comments say about the code. And the debugger is an excellent way to understand how the code really works. I recall exploring both Tk and DBI using this technique.

    It's an obvious point, I know, but what I'm after is clean code that's only as complicated as it needs to be. So while I'm not against commenting, I am against making a fetish of them.

    • I don't find anything wrong with large comments outlining intention. What I (and I think Paul Graham) objects to is something like this:
      $a = $a + 1; # Add one to $a.


      • What I (and I think Paul Graham) objects to is something like this:

        $a = $a + 1; # Add one to $a.

        I also agree with Graham, and I don't think that was quite what he had in mind, especially since he mentioned Perl, and the above type of commenting can crop up in any language.

        One of the main reasons I love Perl is because of its expressiveness: the fact that the language is so malleable that you can craft the code to closely map to the underlying process that it's implementing. And that's what I alway

    • Either point is fine, but I don't see how they are connected. Unreadable Perl code and bad comments don't seem to support each other's validity.
    • Code that's too tricksy to grok should be rewritten.

      Sometimes code needs to be complicated. Some tasks are tough and impossible to oversimplify and that can justify comments. That being said, shoving that code into an appropriately named subroutine should make it easier.

      However, there is one thing that code frequently cannot reveal and that is why something is being done. Maybe it's easy to see that the clone of the customer object does not include their Social Security Number, but that doesn't tel