pericmd 007: Picking a good abstract for application/module

Now let’s move on to abstract. You know, the short sentence that you put after the program name in the NAME POD section:

=head1 NAME

perlbrew - Perl environment manager.

Or, if you use Dist::Zilla, it’s usually the sentence you put in the # ABSTRACT: line:

# ABSTRACT: get, unpack build and install modules from CPAN

There are already a number of good articles on this topic, for example Neil Bowers’ Give your modules a good abstract. In general I agree with what it says and will not repeat the points here. The issue I want to add is: an application distribution will have both lib/App/scriptname.pm which is a module (either one that contains the bulk of the application code, or just a placeholder because a distribution needs the main module) and also bin/scriptname which is the binary/script itself. How should their abstract be written?

I tend to give them both exactly the same abstract. Some people will give lib/App/scriptname.pm something like “Backend module for scriptname”. I avoid this because when the module gets displayed as search results or on MetaCPAN recent page, that abstract is less useful.

Advertisements

Leave a Reply

Fill in your details below or click an icon to log in:

WordPress.com Logo

You are commenting using your WordPress.com account. Log Out / Change )

Twitter picture

You are commenting using your Twitter account. Log Out / Change )

Facebook photo

You are commenting using your Facebook account. Log Out / Change )

Google+ photo

You are commenting using your Google+ account. Log Out / Change )

Connecting to %s