I agree with the importance of naming -- but I don't agree with renaming things.

• Renaming function / method calls : breaks your interface, and backwards compatability.
• Renaming packages / namespaces : same problem.
• Renaming variables : probably not things that users of the code should be worried about, but the odds of introducing errors aren't often worth it.

In your example, you mentioned two cases:

Change of purpose

In this case, there is often a valid time for creating _new_ entities, and in some cases, deprecating the older one. If you add new functionality to a method, sure, it needs a new name -- but it's a new function, not simple a renamed function. If the 'purpose' of the function changes (what it's being used for, as opposed to what it actually does), and the name reflected the purpose, then it may have been named poorly, which gets us to...

A better name becomes apparent

I don't believe I can disagree more with this one. Now, there are cases where you're completely _replacing_ the entity, but if it's just a case of 'I don't like that name, I think I'll name it (x)', you're often asking for trouble. Good documentation about the entities and what their roles are is likely a better solution. I wouldn't want to go through a few hundred or few thousand lines of code making sure I didn't screw something up in the process. (yes, use strict/use warnings are your friend for variables and functions, but keys to hash elements, autoloaded functions, and method calls don't get picked up so quickly). Not to mention the confusion when one of the other programmers tries to come along a year later while you're on vacation, and can't figure out what the hell happened.

Unless you come up with the new name very early in the development process (ie, well before it goes to q&a), I'd be loathe to change it just because a better name came along. Document it, and save it for when you're doing the next major rewrite.

There's no need to break the interface. You can simply extend it (i.e. keep the old method name, or even module). The old method name can redirect to the new one. You can add docs and even warn about the old one being deprecated. How much of an issue this is depends on exactly how public your interface is. If it's in a class in your code base that you know is used no where else, and maybe is only called once or twice, then you don't have to worry. If, at the other extreme, it's a CPAN module, then you have to be a lot more careful, and maybe even never remove the old name.

Still, the effort is worth it to me. I try to think of someone coming at my code (from either a user or a maintainer point of view) completely fresh, knowing next to nothing about the code. They'll find it a lot easier to understand if things are named consistently and appropriately. I'm not suggesting renaming things on a whim, or making a change that's *slightly* better (except during early development as you suggest), but sometimes a method has changed subtley over time, to the point where it's doing something completely different to what it's name suggests. Or sometimes the original name was just plain wrong.

Unfortunately, I don't have time right now to list some examples, but I do have some that I may add at a later date :)

I would prefer "PDF::Puppy::Database::Abstract". But as valdez mentioned, another option is to prefix 'Base', e.g. Base::PDF::Puppy::Database. In hindsight, I'd probably prefer that (or even prefixed Abstract::).

However, there's no real convention here. The important thing is that it makes sense to you, it's fairly clear to anyone who might be maintaining your code in the future, and that you're consistent throughout your codebase.