How does your module's abstract fare?

I've seen lots of bad module abstracts in CPAN uploads. So today I thought let's make a module to evaluate that (dzil plugin coming "soon"). A proof of concept: CPAN::Critic::Module::Abstract. It's modelled after Perl::Critic, with policies/profiles/themes/severity and all that (albeit simpler and not everything is configurable yet). Sample output:


$ critic-cpan-module-abstract ""
.------------------------------------.
| message                 | severity |
+-------------------------+----------+
| Violates prohibit_empty |        5 |
'-------------------------+----------'

$ critic-cpan-module-abstract 'The great new Foo::Bar!'
.----------------------------------------------------------.
| message | severity |
+-----------------------------------------------+----------+
| Template from module-starter 'The great new ' | 5 |
'-----------------------------------------------+----------'

$ critic-cpan-module-abstract 'Perl extension for blah blah blah'
.-----------------------------------------------------------------------.
| message | severity |
+------------------------------------------------------------+----------+
| Template from h2xs 'Perl extension for blah blah blah' | 5 |
| Language not detected as English, 35% da (confidence 0.21) | 2 |
| Saying 'Perl extension for' is redundant, omit it | 3 |
'------------------------------------------------------------+----------'

$ critic-cpan-module-abstract 'perl module to smurf some smurf.'
.-----------------------------------------------------------.
| message | severity |
+------------------------------------------------+----------+
| Violates prohibit_ends_with_full_stop | 2 |
| Saying 'perl module to' is redundant, omit it | 3 |
| Violates prohibit_starts_with_lowercase_letter | 2 |
'------------------------------------------------+----------'

$ critic-cpan-module-abstract 'Kami para penulis CPAN'
.-----------------------------------------------------------------------.
| message | severity |
+------------------------------------------------------------+----------+
| Language not detected as English, 28% pt (confidence 0.91) | 2 |
'------------------------------------------------------------+----------'

$ critic-cpan-module-abstract 'THIS MODULE IS SUPER GREAT'
.-----------------------------------------------------------------------.
| message | severity |
+------------------------------------------------------------+----------+
| All-caps | 2 |
| Language not detected as English, 24% it (confidence 0.48) | 2 |
'------------------------------------------------------------+----------'

$ critic-cpan-module-abstract 'Use this module, dammit!!!'
.----------------------------------------.
| message | severity |
+-----------------------------+----------+
| Too many exclamation points | 2 |
'-----------------------------+----------'

To pass at all, you need to not have any violation with severity 5. To be considered as good, you should have as few violations as possible.

TODO: MORE policies, for example: require starts with verb (infinitive), prohibit repeating module name, consistency with other members of module family (e.g. Acme::CPANAuthors:: or Task::BeLike::), check spelling mistakes, check with existing abstracts on CPAN, etc.

6 Comments

This is a great idea. I put a check for "The great new XXX" in the t/boilerplate.t tests created by Module::Starter in hopes of reminding people to update their abstracts.

Clearly, that wasn't as effective as I would have liked: https://www.google.com/search?q="the+great+new"+site%3Asearch.cpan.org

You've forgotten the classic "Yet another".

qr/yet another/i

As well as "Perl module for" and "Perl extension to", there is also "Perl interface for"

qr/(?:a\s+)?perl\s+(module|extension|interface)\s+(to|for)/i

And don't forget "Perl XS binding for".

qr/perl\s+(?:xs\s+)?binding\s+(?:for|to)?/i

Also, check for capitalization of the initial letter?

By the way, was "Critic CPAN module abstract" meant to be a joke?

I love this idea!

Sad to say that I fall foul of a few rules presented here through ignorance. How was one supposed to know not to end an abstract with a full stop? Now it's clear, and all is good with the world!

And of course I'm wrong, since the verb is critique. Memory of high school English class coming back...
You can also use the verb "criticize", although that has mostly a negative connotation. I think "critique" is a kind of invention made to circumvent the negativity of "criticize".

Leave a comment

About Steven Haryanto

user-pic A programmer (mostly Perl 5 nowadays). My CPAN ID: SHARYANTO. I'm sedusedan on perlmonks. My twitter is stevenharyanto (but I don't tweet much). Follow me on github: sharyanto.