* Andy Lester <[EMAIL PROTECTED]> [2007-06-08 00:15]: > On Jun 7, 2007, at 5:04 PM, Matisse Enzer wrote: > >I wonder how you all feel these days about the "put the pod at > >the __END__" approach? I've been trying it for over a year now > >and am not really sure its the best way to go (vs. having the > >pod for each method right next to it.) > > It's 100% wrong. Put the docs next to the code. It's easier to > see than to think.
Whoa whoa whoa, them’s fighting words. *You* are 100% wrong. Here’s a nickel, get a better editor. </flame> Mine lets me split the window so when it’s time to write docs I have a contiguous view of the POD in one half while referring to the code in the other, which renders your “easier to see than think” argument moot. Documentation should form a coherent narrative. The myopic view of inlined local POD sections is a hindrance to that. Conversely, when I edit code, I occasionally want to shift big swathes of stuff around; having to carry along all the POD before I’m done would bog me down for no gain whatsoever, particularly in light of the fact that such changes generally result in a structucal revision to the docs. Regards, -- Aristotle Pagaltzis // <http://plasmasturm.org/>
