use Perl

• The root problem is interspersing code with POD (Score:1)

  by abw (998) on 2009.07.24 1:50 (#69593) Homepage

  I have to say, I find the whole idea of POD interspersed with code quite loathsome. It appreciate all the reasons why it's a Good Thing (which boils down to keeping the docs as close to the code as possible), but it has so many drawbacks.

  Most notably, it makes it hard to skim through the code when there's big globs of POD getting in the way. If I'm reading the source then it's code I want to concentrate on. If it's the end-user documentation that I want then I'll use perldoc or look at an HTML version of the docs.

  It reminds me of the Bad Old Days when CGI scripts were written as an impenetrable mix of Perl code and HTML markup. We learned our lesson on this a long time ago - a separation of concerns is a good thing.

  Another problem is that it forces you to write your POD to match the structure of your code or vice versa. This is wrong. The end-user documentation should be written from the perspective of someone wanting to use the module. This is an entirely separate thing from the way that the module is implemented internally. After all, that's what programming is about - creating "black box" abstractions that hide the details of the internal workings.

  IMHO, code should be interspersed with comments to explain how the code works, and the end-user POD documentation should be placed at the end of the file. That way you don't have any of the problems with Perl code getting mixed up with POD. Things are badly wrong when you have to change your coding/indenting styling to fit in with the embedded documentation.

  But that's just my HO, of course. Each to his/her own.

  Reply to This

  • Re: (Score:1)

    by chromatic (983)

    Another problem is that it forces you to write your POD to match the structure of your code or vice versa. This is wrong.

    This is the most salient criticism of interspersed POD, in my mind. I spend a lot of time thinking about how to organize prose -- especially technical prose -- and the only case where interspersed POD reads naturally is solely API documentation.
  • Re: (Score:1)

    by moritz (8678)

    When I actually wrote a Perl 6 module with POD I found that I actually duplicated the signatures in the POD, because they are just so expressive.
    
    So I nagged p6l over this duplication (and triggered a huge flame war :/ ), and as a result Damian Conway came up with a way to include parts of the code from within the POD.
    
    Why am I telling you this here? Because that mechanism will encourage interleaved POD, because it's easier to reference something close by. So the Problem won't go away anytime soon.
    • Re: (Score:1)

      by cjfields (3851)

      Interesting, considering in PBP Damian suggests (In Documentation, under 'Contiguity') not to intersperse POD throughout code, for similar reasons already stated here.
  • Re: (Score:1)

    by Hercynium (8027)

    I think you've touched upon something that leads to the root of the issue - the fact that there are several different types of documentation that is produced, each with different display needs and different audiences, and possibly different authors.
    
    Like you said, comments are written by the programmer, for other programmers (including oneself) and are intended to communicate knowledge about the nearby code.
    
    On the other hand, POD's purpose is a little more loosely defined. POD is usually written by the p
    • Re: (Score:1)

      by vrk (9361)

      Exactly! POD is indeed used for multiple purposes; some people have even authored books written in POD.

      However, I find the debate between "POD interspersers" and "POD separatists" boils down to only two usages of POD. The first is to document the API, which is a low-level documentation from one programmer to another. The second is to document the program, which is a high-level documentation from the programmer to the user. Incidentally these two use cases follow closely the preferences of "POD interspers