Wishlists and Modules (was [ANN] libmc)

[steve donovan <steve.j.donovan@...>]

> Anyway, remember - it *is* a wishlist. :-)

While we are exchanging wishlists, here's one of mine ;)

Although code may be free (in both senses of the English word) it can
still be expensive in terms of time needed to understand it.  In an
ideal world there would be as little friction as possible in the
process, i.e. that when using a new module, the accidental complexity
should be as little as possible. (May well be essential complexity,
sometimes things _are_ rocket science.)

A The ideal module:
  0 well named (using namespaces)
  1 well focused
  2 well contained
  3 explicit dependencies
  4 documented in some standard way
  5 adequate test coverage
  6 useful examples

A0 may seem obvious but namespaces are increasingly a must.  CPAN is
looking after 16486 modules (!) and the only way that they can coexist
is by disciplined use of namespaces (e.g [0]).  A project needs a cool
name, but a module needs a useful name.

A2 means that a module behaves itself and doesn't mess with the global
table, except to introduce its own table.  A module can of course be
'injected' into the global table, but only on explicit request.

B And the ideal package manager:
  1 handles dependencies
       (must do this automatically, like LuaRocks [1])
  2 integrated documentation
       (must be available from a central index after installation, e.g
like perldoc)
  3 specifies external dependencies in a useful way
       (in an ideal world, it use the native package manager to find these)
  4 searchable for capabilities and module names
       (e.g. that the module 'lfs' corresponds to the package
'LuaFileSystem' - new LR will do this)
  5 flexible tag-based classification
      (so we aren't tied to a inflexible fixed hierarchy, like the
Trove system [2])

It seems hard to do B2 without A4, without resorting to hacks &
heuristics (is there a README? is there an index.html, perhaps in an
'en' folder? ...) So naturally there have been Lua people interested
in the Perl POD format.

B4 & B5 are related; the idea is to get as much searchable metadata
into the system. And hierarchies can be constructed dynamically from
tags.

B3 is a tough one, which is hard enough to solve for one system (e.g.
Debian) let alone the whole universe of platforms, mostly without
standard library repositories.

This feels like a lot of work, which it is, but the idea is to
minimize the amount of work the producer of the module has to do.
Personally I think LuaRocks is getting there, especially with a nice
front-end; (the next version will be using a more 'normal' way to
manage modules) but delivering module documentation is not a major
concern and writing cross-platform rockspecs remains a bit of an art.
I've even toyed with the idea of writing a wizard for writing
rockspecs ;)

Documentation remains a big weakness.  Probably it's that
psychological illusion that code is self-evident, because one's head
is full of the 'meta-implementation', all that stuff and cogitation
needed to write a program, and which evaporates quickly and leaves us
saying WTF? when reading our own code in six months.

steve d.

[0] http://search.cpan.org/modlist/Option_Parameter_Config_Processing
[1] http://www.luarocks.org
[2] http://luaforge.net/softwaremap/trove_list.php