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!)

---

---

• Are you posting in the right place? Check out Where do I post X? to know for sure.
• Posts may use any of the Perl Monks Approved HTML tags. Currently these include the following:

  <code> <a> <b> <big> <blockquote> <br /> <dd> <dl> <dt> <em> <font> <h1> <h2> <h3> <h4> <h5> <h6> <hr /> <i> <li> <nbsp> <ol> <p> <small> <strike> <strong> <sub> <sup> <table> <td> <th> <tr> <tt> <u> <ul>

• Snippets of code should be wrapped in <code> tags not <pre> tags. In fact, <pre> tags should generally be avoided. If they must be used, extreme care should be taken to ensure that their contents do not have long lines (<70 chars), in order to prevent horizontal scrolling (and possible janitor intervention).
• Want more info? How to link or How to display code and escape characters are good places to start.