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.
  • 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 an

    • 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 always try to do.

        But there are other programmers who, for whatever reason, don't aim to do this; some are merely happy that their code runs at all and just go for the first thing that works. This is where Perl's flexibility gives it a bad name (and hence gets cited in Graham's article): people carelessly drifting towards a working program without being bothered by its form will probably end up with something that is convoluted, and hard to read. This couldn't happen to anywhere near the same extent in a language such as Java, which is so rigid that multiple programmers write almost identical code to each other (that is, even the good programmers are restricted from writing code that is anywhere near as expressive as a carefully written Perl program would be).

        At work I've had to add features to some Perl code that I've found incredibly hard to read. Once I've finally grasped what the code is doing (and why) I feel I should put the knowledge to good use before it gets lost again. One option is to put a comment in the code explaining it.

        Another option is to re-arrange the code (“refactor”, if you like) so that it better reflects the underlying business logic. That's always my preferred option (time permitting): why have hard-to-read code with a comment attached, when instead you can have code that's sufficiently clear it doesn't require a comment?

        I believe that is the point Graham was making.