Beefy Boxes and Bandwidth Generously Provided by pair Networks
go ahead... be a heretic
 
PerlMonks  

Re^3: [literate programming] How to mix POD with code? And how to fold this?

by ssandv (Hermit)
on May 04, 2010 at 22:20 UTC ( [id://838398]=note: print w/replies, xml ) Need Help??


in reply to Re^2: [literate programming] How to mix POD with code? And how to fold this?
in thread [literate programming] How to mix POD with code? And how to fold this?

You don't. You put the pod at the beginning or the end, where it belongs. Code comments should make sense when you have the code in front of you. If you can make pod from them, they're overwritten, and all they're doing is reducing your ability to see the code by shoving it out of the way. Pod is for a level of documentation that makes sense when you're not staring at the code. It's not dual-sourcing because it's not the same information.

Replies are listed 'Best First'.
Re^4: [literate programming] How to mix POD with code? And how to fold this?
by LanX (Saint) on May 04, 2010 at 22:31 UTC
    Did I mention folding? Hmm it's even in the title...

    I prefer folding, it's robust and easy compared to the alternative to realize fancy navigation features to jump from code to corresponding POD and vice versa.

    Cheers Rolf

      Decent POD should include a raft of things that don't have a one-to-one correspondence with the code. Typically the only part that corresponds nicely is the method descriptions, so somewhere before that you have to dump the long description, and somewhere after that belongs stuff like bugs, contact info, see also, usage examples, etc. (Assuming this is a package). It's not worth the tradeoff of putting the user documentation for each method (or function) next to the code, to have to put half of the rest of your POD before the first one, and the other half after the last one.

      And folding is in the eye of the beholding editor, unless you get to dictate how others view your code, or ensure that they never do (in which case, what do you need POD for anyway?). I've *never* seen code with interspersed POD that wasn't substantially harder to read than it would have been if the POD were all at the end, or better yet in a separate file altogether. And my editor doesn't readily fold stuff, but it sure does split-screen nicely. That's hardly a fancy or new feature, since Emacs has had it for about 25 years now, and it makes it easy to look at 2 different places in the file at once--or even at 2 different files.

        Ssandv

        once again you start ranting without having read the whole thread.

        It's all about method description, and I asked about better ways because I'm not too convinced about the shown way. (again READ the thread!)

        You can try to look up what DRY and encapsulation means¹, and if you still wanna flame against ideas from people like Donald Knuth I will not try to contradict you.

        Eppur Si Muove!

        Cheers Rolf

        ¹) forgot docstrings! :)

Log In?
Username:
Password:

What's my password?
Create A New User
Domain Nodelet?
Node Status?
node history
Node Type: note [id://838398]
help
Chatterbox?
and the web crawler heard nothing...

How do I use this?Last hourOther CB clients
Other Users?
Others studying the Monastery: (4)
As of 2024-03-29 12:21 GMT
Sections?
Information?
Find Nodes?
Leftovers?
    Voting Booth?

    No recent polls found