in reply to A new take on affordance.
It's a contract. And you should write the contract.
When you build your class, and if you expect anyone elses application to ever instantiate objects of your class, you must provide the proper documentation. (Having said that, it's always good to provide the docs, even if it's only to simplify your own life n months later. ;-)
The contract is your own POD. Provide a POD for the module, inside your module and also deliver it together with the module.
Anyone that is going to use your module should follow your contract. In your contract you state that "If you use this method, that will be the result". For those that do not respect the contract (and some will try to violate it) the only thing you can say to them is "tough luck" when they complain that your latest release of your module brakes their application. (Assuming that you stick to your own contract. ;-)
OTOH, if you do provide what I call a contract, you are free to make any changes to the internals of your object, as long as the module interface (that you promised in your contract) doesn't change. If you need to change the interface, you might need to re-negotiate it, all depending on your situation. For instance, is this an in-house module where youre business relies on it's behavior, etc.
There's no way you can make sure that no one can access the internals of your module. Not in Perl, neither any other programming language that I'm aware of. Produce a class in C++, compiled and distributed in it's binary form, and anyone with enough skills can manipulate the properties of your object. Crackers do it all day long with a binary editor/debugger.
Everything went worng, just as foreseen.