Beefy Boxes and Bandwidth Generously Provided by pair Networks
Keep It Simple, Stupid
 
PerlMonks  

CPAN Module Evaluation Red-Flags

by bsb (Priest)
on Jul 28, 2003 at 03:30 UTC ( #278327=perlmeditation: print w/ replies, xml ) Need Help??

Alternative title: Modulism - Code Bigotry

When scanning CPAN in that "Surely there's a better way" mode, I use some heuristics (read:prejudices) which roughly sort modules into the good, the bad and the kooky.

I'll search in the problem area, pop tabs for each module, then kill tabs based on the feeling I get from the docs. I'm talking about modules that do address your problem, but in such a poor way that you're better off without them.

I'm interested other peoples red-flags during this initial appraisal. Obviously, they're not absolute and will vary according to the general problem and specific context.
Update: The answers so far have largely been too sensible and rational. Express your inner bigot.

To start out, here's some I've managed to untangle from that "blargh" reaction.
Red Flags:

  • Any of the usual code red-flags which are noticable from the module's docs: it reinvents wheels, uses globals, magic numbers, ... These have been done elsewhere.
  • Massive, nested structures passed into new().
  • It's callbackwards. Requiring an entire callback architecture when a few more methods would do.
  • It parses pseudo-perl data structures or expressions.
  • big_procedure_names_containing_pseudo_arguments
  • It has a "send email" option.
  • Or more generally, the "but wait there's more..." interface. I can use the Extra::SteakKnife module myself, thanks.
  • It's general purpose templating ignorant.
  • Names like EZBlah, or HTML::* (Well, I am more skeptical in the HTML:: namespace than in B::)
  • Tied tightly to a given architecture/set of modules. Double red-flag if I'm anti the prerequisites.
  • The language is uncomfortable with perl terms: we pass in what is known as a "Hash Reference"...
It's not all bad, the above often have converse green flags. Here's some more:
  • Notes on portablility, standards compliance.
  • Intelligent notes on bugs, limits, caveats, subclassing
  • Version numbers and updates, some features marked still experimental.
  • Super-star author.
  • XS version of some critical routine
So what have I missed?

Comment on CPAN Module Evaluation Red-Flags
Re: CPAN Module Evaluation Red-Flags
by Anonymous Monk on Jul 28, 2003 at 05:43 UTC
    So what have I missed?

    The fact that many core modules that you most likely use on a daily basis would set off plenty of red flags.

    A few other points I think you should rethink:

    • it reinvents wheels, uses globals - sometimes an author doesn't want to depend on existing code (particularly if it's not a core module). Sometimes code is too slow (this matters, see perl if you disagree). There are good reasons for using globals! Strict rules of that sort rarely do anyone but the newest programmer any good.
    • or HTML::* - why? There are plenty of exceptionally good modules in that namespace (granted, I think they should almost all be in XHTML nowadays, but close enough).
    • The language is uncomfortable with perl terms: we pass in what is known as a "Hash Reference" - possibly a bad sign, but remember not all documentation is written for experts, explaining simple concepts probably doesn't belong in module docs (links would be better), but there's a lot of gray area here.

    As for flags to add - how about tests? This is a major one I look for.

    Most of all I'd advise you to check the source of modules you deem trustable, if it ends up being no good, take another look at the 'red flag' ones.

      Must ... not ... bite, ... being ... trolled ... nooo...

      A) Prejudices/Heuristics aren't 100%. 1 Red flag != bad. 10 red flags == probably bad.

      B) HTML::* and CGI::* just seem to acquire more flaky modules than B::*, Devel::* or IO::*. I can't imagine why that would be...

      C) This evaluation is simply on the docs or README. Testing or it's absence is rarely evident

        Must ... not ... bite, ... being ... trolled ... nooo...

        Criticizing a method of evaulation while offering constructive suggestions is hardly a troll. What did you expect: "Golly, gee bsb, you sure are smart with your module red-flags and what-not, great work. I hope someday I can be as smart as you." (now that's the beginning of a good troll, but I'll get to the point)

        HTML::* and CGI::* just seem to acquire more flaky modules than B::*, Devel::* or IO::*

        90% of everything is garbage. This applies to modules as well, and since I'd wager there are way more HTML::* modules out there, and there's only so many useful ones that can be written, you get a lot of crap. Very few people are going to write an B::* program as their first module. It's the same reason why there's so more much crud Perl code around than python or ruby. More people, more crappy code. Simple.

        Testing or it's absence is rarely evident

        Automated tests should be provided.

Re: CPAN Module Evaluation Red-Flags
by demerphq (Chancellor) on Jul 28, 2003 at 07:59 UTC

    I don't really use many of your criteria at all. I tend to judge based on if its standard distro (AS distro not Std distro), the modules reputation amongst the community at large, and my colleagues and friends here. But the key is usually the test suite it comes with. (I was suprised that automatic testing was not in your list at all.) If it comes with a comprehensive set of challenging tests and succeeds them all I am usually confident enough to use it in dev/test and if I like it and it meets my needs I will use it in production.

    BTW, IMO Annonymonk wasn't a troll. If he hadnt said a few of the things he did I probably would have as well.

    Cheers, and I hope this thread provides some good nodes, the subject is slightly controversial but also thought provoking. ++ to you.
    ---
    demerphq

    <Elian> And I do take a kind of perverse pleasure in having an OO assembly language...

Re: CPAN Module Evaluation Red-Flags
by adrianh (Chancellor) on Jul 28, 2003 at 08:02 UTC

    Some of my red flags are:

    1. Poor test suite. I have an immense distrust of any module without a good test suite. If all it does is check that the module loads okay then I'm going to be suspicious.
    2. Poor documentation. If I can't understand what the module does from the synopsis and description I usually can't be bothered to read further. If something still has an unchanged POD template from h2xs then I'm very unlikely to look any further.
    3. When there is a module that does something similar and there are no notes on why module X should be used instead of module Y (++ points for explaining when module Y should be used instead of module X).
    4. Bad module names tend to put me off: Things that claim a new top-level name space; Lowercase modules that are not pragmas; Non-descriptive names; etc.

    Update:: Additional red flags

    • Having a long list of fails in CPAN testers
Re: CPAN Module Evaluation Red-Flags
by Corion (Pope) on Jul 28, 2003 at 08:23 UTC

    In addition to the tests above mentioned by demerphq and adrianh, I also look at the following criteria :

    1. Synopsis: Does the module have a good, concise synopsis? Does the code work/compile? Is the synopsis code too long?
    2. Author: Does the author have a history of modules? Has the author a history of coming up with modules, releasing them (with much hype) and then abandoning them half-cooked? (I accuse some super-stars of this)
    3. Prior art / existing wheels: Does the author reference and discuss similar modules? Are the differences mentioned? Are the reasons for reinventing the wheel mentioned?
    4. Binaries / cross-platform: As I develop under three platforms (Win32, Linux, Solaris), I'm interested in whether there is a pure Perl version available, as this means a simple fallback solution in case compilation fails. Did the author cater for platform idiosyncrasies? Does the author care for other platforms?
    5. Bug reporting: Does the author mention a preferred way of bug reporting? Does the author use/know RT?

    perl -MHTTP::Daemon -MHTTP::Response -MLWP::Simple -e ' ; # The $d = new HTTP::Daemon and fork and getprint $d->url and exit;#spider ($c = $d->accept())->get_request(); $c->send_response( new #in the HTTP::Response(200,$_,$_,qq(Just another Perl hacker\n))); ' # web

      Great points :). In particular I think an author's history of maintaining his or her modules is a huge point. Do you really want to have to take on maintenance of a module if they stop? It's something well worth considering.

Re: CPAN Module Evaluation Red-Flags
by greenFox (Vicar) on Jul 28, 2003 at 09:44 UTC
    Here's my list of green flags
    • The module is a standard one in the Perl distribution.
    • The module shows signs of maintenance, ie a release history and/or a recent release date.
    • The module has an active support community such as the Perl-LDAP or Perl/Tk modules have.
    • I have seen the module (often) recommended as a solution here.
    • I have seen the module recommended elsewhere, ie merlyn's columns perl.com article etc.
    • The module has a review here with positive comments.
    • The author is well known in the community.

    I think asking here is a fair approach too, something along the lines of "I am trying to solve X and I have found modules <list> on CPAN of which I can see <blah>, does any-one have any experience with this? " which shows you have thought about it and especially if it comes with a promise to write a review on which ever module is chosen :)

    --
    Do not seek to follow in the footsteps of the wise. Seek what they sought. -Basho

      The module is a standard one in the Perl distribution.

      I agree with this, but you have to caveat it with "which distribution" (there are a few) and "for which version of perl". IMO anything that gets in either the base standard distro or the AS distro at any version is good (beyond version specific stuff like the new 5.8 IO:: modules.)


      ---
      demerphq

      <Elian> And I do take a kind of perverse pleasure in having an OO assembly language...
      ...The module shows signs of maintenance, ie a release history and/or a recent release date...

      But a non-recent release date is not necessarily a red flag. Nicholas Clarke raised this at the YAPC::Europe. Some modules are just perfect the way they are. And releasing a new version just to appear to be a "good" module, seems like a waste of everybody's time to him (and me for that matter).

      So I personally would give this a way lower weight in the determination of the usability of a module.

      Liz

        Right. Just as I don't mind using a 1902 edition of Calculus text book. Still the same Calculus.
        I agree completely, thats why I listed green flags, I am looking for the things that give the module a pass. Also I wouldn't make a judgement based on any one thing on my list I am looking for clusters of ticks.

        --
        Do not seek to follow in the footsteps of the wise. Seek what they sought. -Basho

        MJD said the same thing about Text::Template :)

        Greetz
        Beatnik
        ... I'm belgian but I don't play one on TV.
      The module shows signs of maintenance, ie a release history ...

      I really like to check a module's changelog looking particularly for this:

      • evidence that input from others has helped improve the quality and/or feature set of the module
      I see this as a direct reflection that:
      • people are using the module and pleased enough to want to improve it
      • the module author cares enough about the module to respond well (even to ego bumps)
      • the module is evolving into a better implementation under the best testing - use in the real world
      In the absence of a maillist archive for the module the changelog is a view into how well the module/author/user has succeeded in the real world. This helps me feel good about how well it will succeed in my world.
        Good points ++ I would also see these as evidence of my third point that the module has an active support community- I am looking to see that the module will get supported no matter what.

        --
        Do not seek to follow in the footsteps of the wise. Seek what they sought. -Basho

Re: CPAN Module Evaluation Red-Flags
by grantm (Parson) on Jul 28, 2003 at 10:03 UTC

    A number of examples have mentioned poor documentation, but the complete absence of documentation is far worse (four examples from today. If you can't even be bothered writing a README, why bother uploading? You only get one chance to make a first impression after all.

      IMHO, the first impression people get of your module will be from the POD doc on one of the CPAN search sites (search. or kobesearch., take your pick). I usually don't bother to even look at the README, as in my experiance, most module authors only cut-and-paste what they put in their NAME and DESCRIPTION sections of their POD, plus a little installation note (which usually ends up being identical to every other module on CPAN).

      ----
      I wanted to explore how Perl's closures can be manipulated, and ended up creating an object system by accident.
      -- Schemer

      Note: All code is untested, unless otherwise stated

        I couldn't agree more. So when a module includes no POD and doesn't event include a README (like the ones cited), then you'd need to be fairly dedicated to carry on and work out what it's for.

Re: CPAN Module Evaluation Red-Flags
by enoch (Chaplain) on Jul 28, 2003 at 15:06 UTC
    I have a red flag that no one has mentioned yet:
    • No example code in the POD

    enoch


      Agreed, wholeheartedly -- nothing makes me more suspicious about a module than when the author themselves cannot come up with a simple example of use.

      On the other hand, examples are also a useful 'depth indicator', if you take my meaning. (Which is to say, if there's a "simple example" and I don't even understand how it's being used, it's either not simple or so far beyond me that I can't comprehend -- either way, not my module du jour.)

      -----------------------
      You are what you think.

Re: CPAN Module Evaluation Red-Flags
by cleverett (Friar) on Jul 28, 2003 at 18:28 UTC
    I look for an intelligible synopsis. Self evident code in the synopsis is a very good sign as to the quality of the interface design for me.

    Callbacks aren't necessarily a bad thing. The more important question is, does the interface design allow me to do less and accomplish more?

Re: CPAN Module Evaluation Red-Flags
by kko (Scribe) on Jul 28, 2003 at 20:37 UTC
    I have a big green flag when hunting for modules:
    • It's in the ports tree (I'm an OpenBSD user)
Re: CPAN Module Evaluation Red-Flags
by sauoq (Abbot) on Jul 28, 2003 at 21:45 UTC

    When I see documentation that starts

    Some::Module - Perl extension for blah blah blah
    I steer clear.

    -sauoq
    "My two cents aren't worth a dime.";
    
Re: CPAN Module Evaluation Red-Flags
by bsb (Priest) on Jul 29, 2003 at 03:56 UTC
    More red-flags:
    • Example code is not perlstyle-ish, eg. innappropriate CamelCaps.
    • Capitalized "PERL"
    • Modules with a compatability-with-my-company mode
    Green-flags
    • A License section, in addition to the other standard sections mentioned elsewhere.
    • /"W3C"/i
    • Has a Tutorial, Overview, Introduction or Cookbook.
    I like and use the "references and distinguishes other modules" green flags mentioned by others.

    Brad

Log In?
Username:
Password:

What's my password?
Create A New User
Node Status?
node history
Node Type: perlmeditation [id://278327]
Approved by diotalevi
Front-paged by demerphq
help
Chatterbox?
and the web crawler heard nothing...

How do I use this? | Other CB clients
Other Users?
Others browsing the Monastery: (2)
As of 2014-07-26 08:42 GMT
Sections?
Information?
Find Nodes?
Leftovers?
    Voting Booth?

    My favorite superfluous repetitious redundant duplicative phrase is:









    Results (175 votes), past polls