ModuleNaming

From Perl QA

Jump to: navigation, search

One of the roles fulfilled by modules@perl.org is to provide advice for module authors with respect to naming their modules. We've been doing this for ages but nobody has gotten around to writing down the collected wisdom of the Perl Module Naming Gurus -- until now.

ModuleNaming lists naming conventions currently in use on CPAN, as discovered by KirrilySkudRobert by:

  • investigating CPAN
  • discussion on modules@perl.org
  • discussion with other Perl gurus

These notes do not define CPAN or modules@perl.org policy. They're just an imperfect picture of what I've seen so far.

When I counted, I found approximately 400 ""TopLevelNamespace""s on CPAN. The ones with clearly defined purposes include: 

   Acme::      Silly modules
   Net::       Implementations of networking protocols (usually RFCs)
   DBI::       The DBI module itself
   DBIx::      DBI extensions
   DBD::       DBI database drivers

A TopLevelNamespace should not be a 2-letter acronym unless the acronym is very widely known, eg "NT" or "Qt".

Test:: seems pretty well defined - or am I missing something?

Some some BottomLevelNamespaces also defined: 

   ::Simple        Simple/basic interfaces to more complex modules
   ::Lite          Lightweight implementations of protocols etc

OverGeneralizedNamespaces are those which describe just about _everything_, depending how you think about the problem, and include (in approximate order of uselessness):

  • Data
  • Object
  • Software
  • Text
  • Net
  • Sys

If you find yourself thinking of using an OverGeneralizedNamespace, think about whether you can find somewhere more specific for it. For instance, a module called Data::ParseSomehow could instead belong in Parse::Somehow.

BigPerlApplications get their own TopLevelNamespace under the following circumstances:

  • They're sufficiently well-known in the Perl/opensource community
  • They are likely to have several modules underneath them
  • Multiple authors are likely to want to write modules in this namespace

Examples of BigPerlApplications with their own TopLevelNamespace include:

  • Apache
  • Gimp
  • Jabber

NamespaceConfusion abounds in the following areas:

  • Date/Time
  • WWW/HTML/CGI
  • Geo::Weather/Weather
  • Geo/Geography

AvoidExcessiveAbbreviation in your module naming just as you would for naming variables etc. For instance, a module called XML::XBX was proposed, but ended up with the much clearer name XML::ByExample

Namespaces are BigEndian, which is to say that the most important part of the name comes first. If you have a module that handles multiple types of widgets, call it Widget::Multitype rather than Multitype::Widget, because the fact that it handles Widgets is more useful to know than the fact that it handles multiple types of something. In other words, Namespaces go from general to specific, left to right.

DescribeFunctionalityNotImplementation ... for instance, Foo::Fast is better than Foo::XS. Common things to avoid are:

  • Object
  • OO
  • XS

Rewriting an existing module? Don't just call it Foo2, try to figure out what's actually distinctive about it and call it that. If it's easier to use, call it Foo::Simple. If it's faster, call it Foo::Fast. If it doesn't have a distinctive difference, why are you writing/publishing it at all?

XML:: -- only for parsers etc, or for XML apps? We don't know.

Retrieved from "http://perl-qa.hexten.net/wiki/index.php/ModuleNaming"
Personal tools
Mongers