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.
 Full
 Abbreviated
 Hidden
More | Login | Reply
Loading... please wait.
  • by ziggy (25) on 2003.09.03 15:35 (#23811) Journal
    I took a brief gander at the Perl [torkington.com] and Python [blosxom.com] versions in that order.

    My first impression, after reading each in the browser for about a second each:

    • The Perl version starts with a nice long comment that describes WTF this script does.
    • The Python version starts out with gobs of plaintext
    • Oh, wait, it's not python code
    • Oh, wait, it starts out with """
    • Oh, wait, that's a triple-quoted strong. Where does it end?
    • Oh, wait, the python program starts out with pretty much the same commentary as the Perl program.
    • Oh, wait, the commentary is much the same, but it takes more effort to figure out where the comment is here...[*]
    Now we see why C programmers highlight multiline comments with asterisks on every line, and why C++ introduced the // comment marker.

    Embedding plaintext comments with a pair of multiline comment markers is a baaad idea. It forces too many neurons to fire when you don't have the benefit of syntax coloring...

     

    *: Yes, you could make the same accusations about embedding Pod in a Perl program. But we have different social conventions on when to use pod and when to use comments. And a lot of Pod is found at the end of the file, where there is no overhead to figure out where the program is in a morass of multiline comments...

    • I found the Python """ idiom to be no harder to get used to than HEREDOCs.
      • ...but we don't use HEREDOCs for block comments.
        • You've never seen anyone use a HEREDOC for a block comment? You've lived a sheltered life.

          That particular block comment is special. Python associates it with the class object as a special documentation string (__doc__, iirc).

    • The beauty of the triple quoted string is that the documentation is then part of the code. It's available as __doc__ and available to be referenced from your code. Now you can do nice things with it like provide online help automatically from classes / methods.

      -Dom

      • The Perl version starts with a nice long comment that describes WTF this script does.
      • The Python version starts out with gobs of plaintext.

      Then the files aren't really equivalent. Python's """ foo """ multiline comment construct is more equivalent to Perl's POD, not to heredocs.

      Now if you want to complain about the readability of POD, that's one thing, but it's not fair to criticise the Python script for using the language's documentation mechanism when the equivalent comment in the Perl script would

      --


      --
      DO NOT LEAVE IT IS NOT REAL.

      • it's not fair to criticise the Python script for using the language's documentation mechanism when the equivalent comment in the Perl script would have been using POD to accomblish the same thing.

        I'm not criticizing the script, I'm criticizing the language.

        This isn't about docstrings vs. comments, or Pod vs. triple-quoted strings. It's about making different things look different. The combination of triple-quoted strings and their use as docstrings hurts readability because you have to parse them t