Re^3: (How) Do you document/test your private subroutines?

IMHO, modules should not try to prevent calling or inherting their private methods. They should clearly document that it is a stupid or very stupid idea to do so [...]

[...] This way, I (as a user of the module) have the freedom to mess with the modules internals without resorting to monkey-patching, simply by inheriting from the module and fix what looks broken.

So I, as a module author, should provide an interface which people might need to rely on to accomplish what they need, and document that it's stupid to use it? That might be less work for me in terms of ensuring API stability, but for end users, I think they'd prefer I documented those methods (however obscure they might be) and committed to at least attempting to keep the API stable.

Yes, this is against the basic ideas of OOP. No other class or object should mess with the "private" attributes or methods of an object, and only an exclusive circle of classes should be allowed to mess with "protected" attributes or methods.

The reasons for this are not just theoretical purity; there are very good reasons for classes to have no undocumented methods. And subclassing is the biggest one of those. If I'm writing a subclass of your class, I might want to override some of your methods deliberately. But I sure don't want to override any of them accidentally, so I need to know what they're all called. That alone should warrant making anything you truly need to be private into a coderef.

toby döt ink

Comment on Re^3: (How) Do you document/test your private subroutines?

Replies are listed 'Best First'.
Re^4: (How) Do you document/test your private subroutines? by LanX (Saint) on Nov 12, 2018 at 16:50 UTC
> But I sure don't want to override any of them accidentally underscore _convention() ? > That alone should warrant making anything you truly need to be private into a coderef. But coderefs can't be used for protected routines. Anyway, I have no issues with documenting private routines, as long as it's clear they are not part of the compatibility "contract". Cheers Rolf _{(addicted to the Perl Programming Language :) Wikisyntax for the Monastery FootballPerl is like chess, only without the dice}	[reply]
Re^5: (How) Do you document/test your private subroutines? by choroba (Cardinal) on Nov 12, 2018 at 16:56 UTC
> underscore _convention() That's the problem. If the parent class defines `_frobnicate` but doesn't document it, you might accidentally define `_frobnicate` in the child class (because underscore convention!) to do something completely different, and kaboom! ($q=q:Sq=~/;[c](.)(.)/;chr(-\|\|-\|5+lengthSq)`"S\|oS2"`map{chr \|+ord }map{substrSq`S_+\|`\|}3E\|-\|`7**2-3:)=~y+S\|`+$1,++print+eval$q,q,a, [download]	[reply] [d/l] [select]
Re^6: (How) Do you document/test your private subroutines? by tobyink (Canon) on Nov 13, 2018 at 19:02 UTC
Or worse still, you're writing a child class and carefully check that the parent class doesn't define `_frobnicate`; everything seems good. Then you install an upgrade of the parent class from CPAN, and it defines `_frobnicate`. If the updated parent class had made `frobnicate` a public method then the problem would be pretty easy to track down, maybe even by just reading the Changes file. If the updated parent class had used `my $_frobnicate = sub { ... };` this wouldn't be a problem to begin with. toby döt ink	[reply] [d/l] [select]
Re^6: (How) Do you document/test your private subroutines? (->can) by LanX (Saint) on Nov 12, 2018 at 17:41 UTC
> you might accidentally define _frobnicate in the child class ... and kaboom! for completeness, we might not get a "Subroutine _frobnicate redefined at" warning but it is possible to dynamically inspect a parent class with `->can` from `UNIVERSAL` So it's not that the "sub-class"-developer is completely in the dark. It should even be possible to check this automatically. (which is the saner approach since people don't tend to read the docs after a parent class got extended) Cheers Rolf _{(addicted to the Perl Programming Language :) Wikisyntax for the Monastery FootballPerl is like chess, only without the dice}	[reply] [d/l]
Re^6: (How) Do you document/test your private subroutines? by LanX (Saint) on Nov 12, 2018 at 17:00 UTC
ahh ... I see. I think we have now three documentation levels to be distinguished: docs for the user of the module/class docs for the developer of subclasses docs for the maintainer Cheers Rolf _{(addicted to the Perl Programming Language :) Wikisyntax for the Monastery FootballPerl is like chess, only without the dice}	[reply]


Welcome to the Monastery
	PerlMonks