Mark Swayne

Way back in 2005 I posted my first CPAN module (Log::WithCallbacks). It had proved useful on several different projects, and I thought it would be nice to share. I struggled a bit with namespace selection and was never able to resolve a nasty permissions problem with the tarball I submitted. I got busy with other things, and my poor module got neglected.

Now, I find myself winding down the project that I've been working on for the last 5 years. So, since I have some time on my hands, I thought it would be good to fix those permissions problems and bring it up to current standards of best practices. The first task will be to max out the kwalitee score, then improve the test suite to get close to 100% coverage. Once the test suite is complete, I'll look at improving the code itself.

So I wandered over to CPANTS to check out my score, and found it wasn't as bad as I thought it would be.

First step was to sign up for github. I switched over to git last spring for a major project, and I don't miss CVS at all. With a github account under my belt, I created a repo and was ready to upload some code.

Next, I downloaded a tarball from CPAN and unpacked it, checked it into a local git repo and pushed it to github.

I didn't remember the API all that well, so started reading the code. Several things stood out right away: I didn't use lexical warnings and I had an orphaned import of Symbol. The reason for this was that I originally used this code for a project using Perl 5.005. Niceties like lexical warnings and filehandles weren't available back then.

The API isn't what I'd do now, and I had to take several deep breaths to stop myself writing a brand new module with a rip-roaring new API. But, the last thing CPAN needs is yet another logging module. So, I calmed down and focussed on the task at hand.

Step 1. Kwalitee.

The first thing I decided to work on was improving my kwalitee score. CPANTS is a wonderful resource--thanks to everyone who works or has worked on it. You could be cynical and see my goal of maxing out kwalitee as pointless number chasing. I could regurgitate useless docs and fool the scoring system into giving me good numbers. But thats a huge waste of a great tool.

I prefer to see metrics like this as tools that help remind me to do the right thing. Having a proper README file or a change log is a good idea. Sure I could get by with touch Changes and fool the computer. But the real score keeper is me. I'd know I cheated.

Module::Build

I decided to switch from ExtUtils::MakeMaker for my build process to Module::Build. MB beats EUMM by providing many helpful targets (actions). META.yml generation and smart MANIFEST management were big bonuses. I also like the fact that I can generate a Makefile.PL in my distribution, so that MB is not a requirement to install.

Module::Starter and POD Testing

I didn't have any POD testing. To fix that, I fired up Module::Starter and used that to create a dummy new version of my module. I then took the pod tests it generated and plopped them into my directory. While I was at it, I snagged the README file template and fixed it up.

Writing examples

Writing useful examples is tricky. A good example should be didactic and persuasive. It should show how to use key features, and why they are useful. I put together an example to shows how to use LWCb to create a simple Logging library with logging levels. I think I need to put together another example that shows how to leverage the callback functionality.

Once I finished these changes, I pushed to github.

In the next installment, I'll talk about updating my test suite and improving my test coverage.