Error handling and messages
When your module encounters an error it should do one or more of:

  Return an undefined value.

  set $Module::errstr or similar (errstr is a common name used by DBI and other popular modules; if you choose something else, be sure to document it clearly).

  warn() or carp() a message to STDERR.

  croak() only when your module absolutely cannot figure out what to do. (croak() is a better version of die() for use within modules, which reports its errors from the perspective of the caller. See Carp for details of croak() , carp() and other useful routines.)

As an alternative to the above, you may prefer to throw exceptions using the Error module.

Configurable error handling can be very useful to your users. Consider offering a choice of levels for warning and debug messages, an option to send messages to a separate file, a way to specify an error-handling routine, or other such features. Be sure to default all these options to the commonest use.