How not to recommend a Perl module

The first comments in response to my Anatomy of ylastic-costagent article were recommendations to consider other modules than the ones I used. Frankly, these module recommendations sucked, and I’m annoyed enough to explain why.

The first recommendation was to consider Date::Simple instead of Time::Piece + Time::Piece::Month, but Date::Simple doesn’t appear to solve my problem.

I was looking for a way to find the first day of the next month (without manually incrementing the month and potentially the year). Here’s how I did it:

# returns a Time::Piece object
Time::Piece::Month->new( Time::Piece->new() )->next_month->start()

Note that Time::Piece::Month has a next_month() method. Does Date::Simple offer a way to do that? Not that I can see in the documentation, so the recommendation is useless to me.

The second recommendation was to use Log::Any::App instead of Log::Dispatchouli. Leaving aside that I said the reason I was using Log::Dispatchouli was because I was explicitly trying to learn it, the recommendation suggested that I could have “1 instead of 6” lines of code.

Here’s my “six” (actually about 8) lines:

local $ENV{DISPATCHOULI_PATH} = $opts->get_logpath
  if $opts->get_logpath;

my $logger = Log::Dispatchouli->new({
  ident     => basename($0),
  facility  => $opts->get_syslog ? $opts->get_syslog : undef,
  to_file   => $opts->get_logpath ? 1 : undef,
  log_pid   => 0,
  debug     => $opts->get_debug,
});

Note that I’m setting a name, optionally logging to syslogd, optionally logging to a file of a user-defined path (and potentially doing both), and toggling a debug mode.

Looking at Log::Any::App’s usage synopsis, here’s what I see:

use Log::Any::App qw($log);

Yes, that’s one line. But does it provide the same options? Obviously not in just that line. If I read to the end of the documentation, I find there is an init() function and I can do something like this (N.B. untested):

require Log::Any::App;
Log::Any::App::init([
  '$log',
  ($opts=>get_logpath ? (-file => $opts->get_logpath) : () ),
  ($opts=>get_syslog ? (-syslog => { facility => $opts->get_syslog) }) : () ),
  ($opts=>get_debug ? (-level => 'debug') : () ),
]);

I don’t know if that really does exactly the same thing – it looks like it would get close, but it’s certainly not “1 line versus 6”.

In evaluating the two modules, I compare whether documentation makes it easy to figure out how to use each module. Here are the two synopses together for comparison:

# Log::Any::App
use Log::Any::App qw($log);

# Log::Dispatchouli
my $logger = Log::Dispatchouli->new({
    ident     => 'stuff-purger',
    facility  => 'daemon',
    to_stdout => $opt->{print},
    debug     => $opt->{verbose}
})

One of those shows me how to configure it to suit my needs. The other doesn’t. Log::Dispatchouli also documents its new() method and all arguments within half a page after the synopsis. Log::Any::App buries its init() documentation towards the end of the documentation (and also doesn’t mention that it will take a variable name to export to, just like on a “use” line).

If the recommendation had said, “if you want a logger that gives you decent defaults without configuration”, I might have found the recommendation more useful, but that is not what it said. Unless it’s obvious from the docs, a recommendation should tell me how to do the same thing easier/faster/better than what I’ve already done. If it’s not obvious, write an example yourself, or don’t bother with the recommendation.

Log::Any::App actually seems decent, but if I wasn’t annoyed enough to write this article, I probably wouldn’t have bothered to read past its terrible synopsis.

How not to recommend a Perl module

If you recommend a module, make sure it solves my problem 🔗︎

If you recommend a module, make sure I can see how to use it 🔗︎