in reply to Re: Documentation: POD vs Comments (visual)
in thread Documentation: POD vs Comments

> Because whether "code" is really code or not depends on whether one of the hundreds of '=' characters in the previous 10 pages happens to be in the first column and also whether that closest prior such '=' is followed by 'cut' or any other word.

As a side note, IIRC you don't use syntax highlighting.

Cheers Rolf

  • Comment on Re^2: Documentation: POD vs Comments (visual)

Replies are listed 'Best First'.
Re^3: Documentation: POD vs Comments (visual)
by JavaFan (Canon) on Jul 22, 2011 at 09:21 UTC
    "use syntax highlighting" is really a poor defense. I'd say that code that isn't readable without syntax highlighting is just that: unreadable. One doesn't always have the luxury of using the editor that's tuned to your preferences - you may be looking at someone elses screen. Or you're debugging some code on a box that only has vi. (And when I mean vi, I mean vi. Not some vi clone renamed to vi). Or you may be reading code outside an editor (more, git blame, ...). Some people don't even have the luxury of easily distinguishing between colours - or they need the black-on-white constrast; any other colour just won't do.

    I always write my code assuming the next person looking at the code uses ed and a 80x24 glass monitor, knows my address, and is a sociopath who keeps his axes sharp.

[reply]
[d/l]
      "use syntax highlighting" is really a poor defense. I'd say that code that isn't readable without syntax highlighting is just that: unreadable. One doesn't always have the luxury of using the editor that's tuned to your preferences

      Can you imagine a doctor eschewing the use of a stethoscope, because one day he might encounter an emergency when he hasn't got it with him?

      Examine what is said, not who speaks -- Silence betokens consent -- Love the truth but pardon error.
      "Science is about questioning the status quo. Questioning authority".
      In the absence of evidence, opinion is indistinguishable from prejudice.
[reply]
      I didn't say "use syntax highlighting", I just wanted to clarify from which perspective tye is looking at the issue.

      Cheers Rolf

[reply]
Re^3: Documentation: POD vs Comments (visual)
by tye (Sage) on Jul 22, 2011 at 09:24 UTC

    Do you use syntax highlighting... in your diff tool? In your merge tool / conflict resolver? In your grep tool? In your print-outs? In your code reviews? In your e-mail? In your 'blame' tool? In your repo browser? etc.

    And how do you manage to understand the example code in the POD if the colors aren't right?

    Of course, even when you are in a context where you can have your color hints crutch, POD still gets in the way of reading code.

    As a side note, IIRC, you use emacs.

    - tye        

[reply]
      Even if the diff tool had syntax hilighting, it usually wouldn't have enough context to know if a chunk is part of a POD block or not.

      Update: An actual diff tool usually has enough context, just a tool for viewing a patch/diff usually doesn't.

      Perl 6 - second systems done right
[reply]
      Do you use syntax highlighting... in your diff tool?
      I love vimdiff. It can be really helpful if you have more complicated diffs. The code has syntax highlighting and additionally the different lines are coloured.
[reply]

        Other than the sad scenario of leaving ${EDITOR:-vim}, what do you think of meld?

        After working with meld, I found myself lost when presented with "emerge" window. I should really look into a ${"merge tool":-vimdiff} that runs in xterm. (sdiff(1) -- while using "mergemaster" -- is too tedius to work with when faced with lines longer than a few words.)

[reply]
      > As a side note, IIRC, you use emacs.

      good point there you can indeed diff with intact syntax highlighting! :)

      Cheers Rolf

[reply]

In Section Meditations