Stories
Slash Boxes
Comments
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.

Comments make Perl unreadable, says Paul Graham 17 Comments More | Login | Reply /

 Full
 Abbreviated
 Hidden
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.

      -Dom

      • 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

  • > Comments aren't there to explain the mechanics,
    > but to document the state of mind.

    Agreed. However, not all folks use comments in that manner.

    If your code implements a diagonal proof at one point, Paul would probably be unopposed to a comment referencing what such a thing is (assuming that the expected maintainers of the code would not already know). In a mathematics department, the comment is probably uneccessary. If you found cause to use a diagonal proof in your flowchart layout generation code
  • I have two opposing examples of languages that are more likely to need comments than others: regexps and T-SQL (Sybase/SQL Server). One is extremely terse, one is extremely verbose.

    Regexps are usually very compact and opaque. Your comment about whitespace is spot on, so /x should obviously be encouraged. But even with a sanely laid out regexp, the pattern of a regexp usually needs comments to indicate exactly what (\w+-\d) means in the context of a program. The regexp syntax itself doesn't allow us to do t

    • When it comes to Perl, I find that using implicit $_ often obscures the code. Not using an explicit variable means a missed opportunity to self-document the code by naming the variable properly.

      I think the exact opposite. $_ has a meaning in Perl: “the current ‘thing’ being operated on”. That's a well-defined convention, and it has the advantage of being the same in every program.

      In other languages when people want a temporary variable they often use i or n or s, but they aren'

      • Using $i as a loop variable doesn't increase readability unless it is to communicate that "it's just a loop variable" and that's seldom the case since the Perl foreach is so much more useful than the C-style for loop.

        If the code block is very brief, like in

        dostuff($_) for(@servers);

        then I agree that it isn't necessary to alias it to a new name. But if the code block is longer than a few lines, it's indeed very useful to have an actual name connected to the entity you're dealing with.

        Consider the followi

  • Comments make Perl unreadable, says Paul Graham

    I'm not fond of seeing such misleading attributions. I'll try to give you the benefit of the doubt and assume that you actually think this is what he is saying, but I have a difficult time seeing how you (or anyone) can come to that conclusion.

    If Paul had stated,

    The way to get rid of the stench of spoiled food in an apartment is not to spray a bunch of air freshner.

    Would it make sense to summarize it as follows?

    Air freshner makes apartments stink, say

    • His comment is that Perl is unreadable, and the end note to support that says that comments are an abomination. As I said in my post, I don't see how he connects the two. Either statement is fine by itself, but not together: hence, the title.

      Indeed it is poor logic, but it is what he uses to support that Perl is unreadable. I don't know why he connected those two. What do you think it means when he connects those two things?

      • His comment is that Perl is unreadable, and the end note to support that says that comments are an abomination.

        I don't think that's what he's saying at all (neither point, in fact). His point is that comments don't guarantee programs that are "written for people to read, and only incidentally for machines to execute."

        Indeed it is poor logic, but it is what he uses to support that Perl is unreadable.

        I meant that your summary was poor logic. It's the classic logic problem. If A, then B. Does this mean

        • I understand logic so you don't need to explain it. I think Paul makes a leap in logic. That's my point. That's what I discuss in the post, and that's why I chose the title. It's ironic. See the title in the context of the post. It's not what he says, it's that he connects them. It's very clear in the post that I don't know what he's actually trying to say.

          The two statements I pulled out do not connect with each other, but Paul specifically and on purpose connects them. He's using one to support the o

  • I don't think that Perl code needs comments more than any other code.

    This is where you're getting tripped up. :)

    Here's my version of Graham's logic:

    1. Lots of hackers write terse, fancy, etc. code that's hard to decipher when they come back to it 6 months later.
    2. The way to make your code easier to remember isn't by adding comments everywhere, but by reworking the code to be simpler and easier to understand.
    3. Perl is so fucking nasty that there's no way to do Step 2; therefore, so you're forced to a
    • I guess that could be that point, even if I don't agree with it.

      As I've been thinking about this and trying to get into his mind, and I have the feeling he may be talking about people who tried Perl for a couple of days and then stopped. Six months later they can't remember anything from those two days. That's not surprising.

      Or, he's talking about people who tried to understand somebody else's code and gave up after a couple of days. Well, I have that problem with a lot of code no matter the language.
  • Here's Paul's comment and footnote in their entirety:

    You need to have empathy not just for your users, but for your readers. It's in your interest, because you'll be one of them. Many a hacker has written a program only to find on returning to it six months later that he has no idea how it works. I know several people who've sworn off Perl after such experiences. [7]

    [7] The way to make programs easy to read is not to stuff them with comments. I would take Abelson and Sussman's quote a step further. Pro

  • It thought what he was saying was quite clear, if pretty silly. He's saying that Perl tempts people to write confusing code, which they usually react to by adding comments to hopefully later remind themselves of their mental pirouettes.

    To which I reply “You are correct, sir, but it's a poor craftsman who blames his tools.”

Stories, comments, journals, and other submissions on use Perl; are Copyright 1998-2006, their respective owners.