Beefy Boxes and Bandwidth Generously Provided by pair Networks
Do you know where your variables are?
 
PerlMonks  

Re^2: Private Methods Meditation

by ihb (Deacon)
on Jul 20, 2004 at 00:46 UTC ( [id://375749]=note: print w/replies, xml ) Need Help??


in reply to Re: Private Methods Meditation
in thread Private Methods Meditation

Personally I just put an _ in front of my private methods and a comment tell people "This is private, use at your own risk".
Tell me, do you also document it? If you do, you belong to an extremely small minority.

ihb

Replies are listed 'Best First'.
Re^3: Private Methods Meditation
by stvn (Monsignor) on Jul 20, 2004 at 02:16 UTC
    Tell me, do you also document it?

    Do you mean document, as in comments? Almost always yes, unless the code itself is so glaringly obvious that it needs no documentation.

    If you mean document, as in POD? Then the answer is sometimes. Documenting private and protected methods in POD is only really useful for those who want to subclass your module, and I try to make sure to point that out when I do so as not to confuse.

    -stvn
Re^3: Private Methods Meditation
by tilly (Archbishop) on Jul 20, 2004 at 15:58 UTC
    Why would someone want to document private methods?

    Documentation is a promise that something won't change. Part of the point of keeping private methods private is that they might change in future versions. Those goals are in conflict with each other.

      Why would someone want to document private methods?

      Because in Perl if you just use the leading underscore convention and the -> calling style you can have problems with subclasses using the same method name.

        This does not strike me as a good reason.

        Experience strongly suggests that if you use descriptive method names, collisions are rather rare, documentation is never accurate, and it is as easy to search code for private methods as it is documentation. (Besides, I'm always going to search the code in the end because I don't trust the documentation.)

        Furthermore no amount of documentation can protect you if the base module's implementation changes and it now needs a new private method that might intersect what some subclass is using.

        This is part of what I was referring to at Re^2: Private Methods Meditation. And there is no perfect solution to it. However after you use descriptive method names and have decent test suites, the problem virtually goes away. If you furthermore have somewhat decent designs, the issue becomes rare to the point of being an endangered species.

        I'll continue my practice of not documenting private methods in POD. They are in source code, and possibly in regular comments when needed. That is good enough.

Log In?
Username:
Password:

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

How do I use this?Last hourOther CB clients
Other Users?
Others lurking in the Monastery: (5)
As of 2024-04-25 19:59 GMT
Sections?
Information?
Find Nodes?
Leftovers?
    Voting Booth?

    No recent polls found