Reviewing Perl Best Practices, Chapter 15, Objects

Perl Best Practices (PBP) was released in 2004, about 7 years ago. Perl is a great language, but its culture of TIMTOWTDI can be a problem. These days, we often hear that “there’s more than one way to do it, but sometimes consistency is not a bad thing either” (TIMTOWTDIBSCINABTE). PBP deserves a lot of credit for encouraging discussion about the downsides of TIMTOWTDI. PBP has a lot of recommendations. A lot of them are fairly trivial, like recommendations on code formatting.

Who Are the Perl 5 Core Docs For?

I’ve been spending a fair bit of time working on Perl 5 core documentation. I started by editing and reorganizing some of the documents related to core hacking. This update will be in 5.14, due to be released in April. I’m also working on replacing the existing OO tutorials and updating the OO reference docs, though this won’t make it into the 5.14 release. There’s been a lot of discussion on my OO doc changes, some of it useful, some of it useless, and some of it very rude (welcome to p5p!

What Makes for a Perfect OO Tutorial Example?

Recently I’ve been working on revising the Perl 5 core OO documentation, starting with a new OO tutorial. My first draft used Person and Employee as my example classes, where Employee is a subclass of Person. After I posted the first draft, several people objected to these particular classes. I realized that I agreed with their objections, but I wasn’t able to come up with anything better. I brought this up on the #moose IRC channel, and we had a really interesting discussion.

Changes File How-To Follow-Up

My last post on Changes files purported to be both a how-to and how not-to, but I got a bit carried away with the how not-to part. Several comments since that post made excellent points, so here’s the summary. Kent Fredric says “don’t be lazy and just copy the output from ‘git log’ into your Changelog.” Yes, a thousand times yes! Remember, the Changes file is for end users of your library, and we don’t care about all the little details.

Changes File How-(and How-Not-)To

Every software release should come with a list of changes that are present in that release. What goes in this list depends on your audience. Let’s consider a changes file for a module released on CPAN. For a CPAN module, the audience is other developers. Some of the readers have used this module before, and want to know what’s new. Other readers haven’t used this module, and want to know if the changes in this release will change their minds.

CatalystX::Routes, Sugar and Power

I’ve just released a new module, CatalystX::Routes, which adds a layer of sugar for declaring Catalyst actions (aka URI mapping, routes, etc). Route declarations work together with the Catalyst::Action::REST distribution to make it trivial to declare RESTful actions in your controllers. I’m very excited about this module for several reasons. First, Catalyst’s sub attribute-based action declaration is hideous. I cringe every time I look at it. The syntax is also un-Perlishly picky.

Config Versus Code

I was looking at some $WORK code recently. It had a lot of “stuff” in configuration. This seemed wrong to me, but I wasn’t sure why it bugged me. Thinking about it more, I realized that I had developed a set of unarticulated rules that guide my thinking about configuration. These guidelines are applicable to more than configuration. A setting can be exposed to non-developers through a configuration file, command line switches, environment variables, etc.

Creating the Perfect Anti-Harassment Policy

First, my apologies, as this isn’t strictly related to either activism or programming, but it touches on both. Recently, the programming community has been talking about anti-harassment policies in light of a recent incident. More recently, my animal rights group, Compassionate Action for Animals, was confronted with the need to create our own policy. Having a public policy in place is important. It makes it clear that the conference/organization takes harassment seriously, and provides a clear direction on how to report alleged harassment.

What I’ve Been Working on Recently(ish)

I’ve written quite a few new modules in the past few months, but I haven’t really written about them. Here’s a summary of recent(ish) releases. Silki (Ok, this isn’t really recent, since the first release was in May.) Silki is a wiki application built with Catalyst and Fey::ORM. Silki is a multi-tenant wiki hosting system. Translated into English, that means that once you install Silki, you can host many wikis, each of which can have totally different sets of users.

CPAN API Review: DateTime and DateTime::Duration

I’ve been thinking of writing some CPAN API review blog posts. There’s a lot of bad APIs on CPAN. But before I pick on other people’s modules, I thought it would be good to start with something of my own. The first release of DateTime was in early 2003. There’s 7+ years of mistakes to review, but I’ll just hit the highlights. Duration and subtraction APIs In my experience, the single most confusing part of the distribution is DateTime::Duration API.