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.
  • There isn't actually a problem in the interaction of methods and pod, when you consider that the "problem" is based on false assumptions.

    One false assumption is that methods have to be indented when you have a block class in order to be pretty; I disagree, and methods can be flush left just like their pod, so all pretty so far.

    Another false assumption is that you can't have block classes in Perl 5, and so what worked for Perl 5 can't work for Perl 6; in fact you *can* have block classes in Perl 5, and I hav

    • There isn't actually a problem in the interaction of methods and pod, when you consider that the "problem" is based on false assumptions.

      One false assumption is that methods have to be indented when you have a block class in order to be pretty; I disagree, and methods can be flush left just like their pod, so all pretty so far.

      I had this discussion with Tene yesterday after writing the blog post. He said the same thing [perlgeek.de].

      I think I started to value indenting everything many years ago, when I wrote my first medium-sized application (in BASIC) without indentation, and got into a situation when I had to find a missing 'END' somewhere. Everything I've been doing since then has reinforced the idea that consistently indenting things is a really, really good thing.

      But you're right: making an exception in this case would solve the whole thi

    • One false assumption is that methods have to be indented when you have a block class in order to be pretty; I disagree, and methods can be flush left just like their pod, so all pretty so far.

      This is an interesting issue in Perl because now TIMTOWTDI makes a real mess of things. Frankly, I don't want my methods to be flush left because if I scan down the code, I like my indentation to instantly give me a hint of scope. If the method is indented, that gives me information that left justification won't. So let's say I have two classes in one package. The structure can look like this:

      class
          method
          method
          method
      end
      class
          method
          metho

      • Thank you, Ovid. You put words to what was only an indistinct feeling for me. I agree fully, I also don't want to sacrifice indentation within classes.

        But I also want my Pod. Maybe I'll end up putting the Pod at the end of each file, and then writing some tests to make sure the Pod doesn't drift away from the methods themselves.

      • I agree that indenting methods relative to classes does look better, and I even do that myself some times.

        Mainly I find that the indenting works best when individual classes are fairly small in the amount of code department, and similarly in those cases I generally don't use the dividing lines I mention.

        Where I don't find indenting necessary is when classes are large or there are a number of large methods (ones that fill a screen or more), so that say you've got hundreds to thousands or more of code lines i

  • MooseX::Declare adds a block style class to Perl 5 and I have been running into the same POD problem.

    • Ah! I actually suspected as much when writing the post, but I didn't want to complicate the point further by mentioning MooseX::Declare. Thanks for confirming my suspicion.

  • people who commented things out by putting #s at the absolute beginning of lines might accidentally create embedded comments by placing their # next to a curly brace or a parenthesis or a bracket. [...] I've now learned to put ## at the beginning of lines I want to comment out instead of just #.

    Is it too late to spec this in S02 the other way around? Let single # be used for commenting out, no matter what follows. Let ## (perhaps also ### and so on) switch on the special behaviour of brackets etc.

    The rati

    • I kinda like that way of thinking. And no, it's not too late to spec things differently.

      However, if you want your proposal to be noticed and possibly acted upon, you really should send an email off to perl6-language [perl.org]. That's where language features and spec changes are discussed.

    • Hmm, a row of hashes, optionally followed by other text, is often used for a separator, so there is still some potential for getting "special" meaning where none was intended if multi-hash is changed to mean "special" handling.

      How about making the special codes a bit harder to get by accident?  Something like #{#  ... #}# - with no whitespace permitted between the braces and the enclosing hashes - for a block delimited comment, perhaps.  That would only be an accidental hazard for people who
  • 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

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

    • 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.
      • Interesting, considering in PBP Damian suggests (In Documentation, under 'Contiguity') not to intersperse POD throughout code, for similar reasons already stated here.
    • 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
      • 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