SPUG: Re: Using mkpath (was: HTTP::Cookies question)

[Colin Meyer]

On Fri, Mar 01, 2002 at 10:59:55AM -0800, Richard Anderson wrote:
> Thanks for the correction.  Since File::Path is part of the standard Perl
> distribution and is five years old, I would have expected accurate
> documentation.  Perhaps I should have looked elsewhere than "perldoc
> File::Path"?  Is this (I hope) an aberration or are module users expected to
> scan the source code before using a module?

Well, I should hope that modules would be useful without needing to read
the sourcecode.  I think that is the holy grail of reusable code, OO or
otherwise.

Unfortunately that just isn't always the case. Especially with CPAN
modules, where there is no standard for entry. They even let *me* upload
a module for any fool^h^h^h^h programmer in the world to use.

I am in the habit of reading the source to CPAN modules.  It is really
a neat thing to have such an enormous repository of incredibly diverse
code.  I do this for a hobby, in my spare time.  I hate having to read
module code at work, while I should be thinking about my own problems.  

One would expect that core modules would need to pass some inspection of
the peer community, and they do: it's called p5p, and its echos. Jarkko
has recently put out the call for folks to heavily test core modules to
be included with soon-to-be-shipped 5.8.0. However, it is sadly true
that no group of programmers, however clever they may be, are perfect.

Perl is an open source, community oriented project. I think that if we,
the users of Perl, agree that modules should be usable by reading their
documentation, then it is our responsibility to make sure that they are.

I've mailed a patch of a suggested documentation change to Tim Bunce and
Charles Bailey, authors of File::Path.  

Unfortunately, this is a core module and it is very unlikely that it
will be updated from the CPAN on most Perl installations. Maybe they'll
change the docs in time for shipping with 5.8.0.  As an aside, Ingy's 
NAPC concept will help address the staticness of core modules.

Have fun,
-C.

 - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
     POST TO: spug-list at pm.org       PROBLEMS: owner-spug-list at pm.org
      Subscriptions; Email to majordomo at pm.org:  ACTION  LIST  EMAIL
  Replace ACTION by subscribe or unsubscribe, EMAIL by your Email-address
 For daily traffic, use spug-list for LIST ;  for weekly, spug-list-digest
     Seattle Perl Users Group (SPUG) Home Page: http://seattleperl.org