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

    • 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

      • 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 in one class. Generally speaking, indenting is more valuable within a local context than within a much wider context.

        The main reason I have methods flush-left within larger classes is that horizontal screen real-estate is valuable and it seems a waste to not use a whole indent level for many thousands of code lines in order for exactly 2 lines to be further left than those. Especially since I strictly limit my line lengths to 75 characters and I use 4 character indents.

        My practice has nothing to do with pod. In fact, I think mixing pod with code is a bad idea, and I put all my pod at the end of the file. While I keep my docs for classes and methods in the same order as their corresponding code in general, I believe in writing documentation for the users, and it can be more natural if it is separate; similarly the code can be easier to read.

        I write # comments in the few cases where code actually should be explained for code-readers beyond what the user pod says.

        So if people want to indent methods, I have no objection save ineffectualness and wasted space.

        I will say though, that regardless of whether I indent methods in a class, I always indent other class contents like attribute declarations.