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.
| [reply] [Watch: Dir/Any] |
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.
| [reply] [Watch: Dir/Any] |
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!
¹) forgot docstrings! :)
| [reply] [Watch: Dir/Any] |