http://www.perlmonks.org?node_id=916044


in reply to Documentation: POD vs Comments

One of the biggest differences between POD and comments for me is that comments don't look like code while POD is not easily visually distinguished.

One of the nice things about POD is how easily and naturally you can include sample code in your POD. So I find it very likely that sample code will get included in POD. And trying to read the actually code when it is shuffled together with POD that includes sample code actually feels like a nightmare &emdash; like I'm just going along opening this innocent-looking file of Perl code and suddenly I realize that it is "finals" and I haven't studied and then everybody is laughing at me because I'm also naked, er, I mean, I suddenly realize that I can't even find the code.

Because, instead of the file containing a block of code that I can read or scan or scroll through or search through, the file contains some twisted "scavenger hunt" where I think I've found some code but it is really just text that looks like code. And when I find the code, I have a hard time concentrating on it to understand it because I'm not confident that I really did find it this time.

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.

Comments require that the fairly distinctive '#' be present on every line. POD actually requires that the ubiquitous '=' character be separated from what you are looking at by at least one blank line.

But even without embedded sample code in your interleaved POD, I find that the POD can greatly interfere with the reading of code, especially for some types of reading (especially less linear types). So please don't interleave POD and code.

Yes, I understand the theory of "keep the documentation close to the code so that when somebody changes the code they'll also change the documentation". But I don't believe it actually works that well. The documentation gets updated most when the documentation gets used. So I think you get better results by concentrating on writing useful documentation.

And it is easier to make documentation useful when you can structure the documentation usefully, not be constrained to a structure that makes sense when shuffled together with your code.

So use comments to explain things that somebody trying to read the code needs to understand. Use POD to write documentation to be used by people who are trying to make use of your code. Quite different audiences who want quite different information. And keep the POD away from the code (such as after the __END__ marker or in a separate *.pod file).

- tye        

Replies are listed 'Best First'.
Re^2: Documentation: POD vs Comments (visual)
by LanX (Saint) on Jul 22, 2011 at 07:36 UTC
    > 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

      "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.

        "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.
        I didn't say "use syntax highlighting", I just wanted to clarify from which perspective tye is looking at the issue.

        Cheers Rolf

      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        

        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.

        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.
        > As a side note, IIRC, you use emacs.

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

        Cheers Rolf