I'm running into this right now with a large optimization of DBM::Deep. As in every non-trivial piece of code, there's a lot of codesmells all over the place. I've tried doing some documentation, but it's all gone out of date very quickly.

To me, I think the biggest key is to remove as many codesmells as possible. In doing so, the code becomes more self-evident. And, with a little reflection, that makes perfect sense. A codesmell is a place where someone goes "Why would you do that??" If you remove a codesmell, you remove a question in the reader's mind.

That said, there are places you will always need to explain something. About 6 months ago, I started signing and dating all my comments, especially in projects where I'm the only developer. Obviously, I know I made the comment. But, as it turns out, the date on the comment has proven more useful. This is because knowing the order of the comments helps to remind me what my thinking was at that time. Since I started doing that on a $work project, I have come back to DBM::Deep where I don't have dated comments and the contrast was very stark. I feel lost without that historical context.

If I need more than 120 characters to explain something, it's either a horrible problem with something I'm using or I screwed up somewhere. Usually, it's the latter and I need to rewrite. So, the comment gets an XXX (or TODO) on it.

As for POD, there is very little in the way of auto-generated POD. All that stuff is written by someone, often the developer. I would love to see more non-developer-written POD as that documentation tends to be of higher quality. (This is especially true for my modules!)