CONTENTS

• NAME
• INTRODUCTION
• QUICK CHECKLIST
  • Before you start
  • The API
  • Stability
  • Documentation
  • Release considerations
• BEFORE YOU START WRITING A MODULE
  • Has it been done before?
  • Do one thing and do it well
  • What's in a name?
  • Get feedback before publishing
• DESIGNING AND WRITING YOUR MODULE
  • To OO or not to OO?
  • Designing your API
  • Strictness and warnings
  • Backwards compatibility
  • Error handling and messages
• DOCUMENTING YOUR MODULE
  • POD
  • README, INSTALL, release notes, changelogs
• RELEASE CONSIDERATIONS
  • Version numbering
  • Pre-requisites
  • Testing
  • Packaging
  • Licensing
• COMMON PITFALLS
  • Reinventing the wheel
  • Trying to do too much
  • Inappropriate documentation
• SEE ALSO
• AUTHOR

#NAME

perlmodstyle - Perl module style guide

#INTRODUCTION

This document attempts to describe the Perl Community's "best practice" for writing Perl modules. It extends the recommendations found in perlstyle , which should be considered required reading before reading this document.

While this document is intended to be useful to all module authors, it is particularly aimed at authors who wish to publish their modules on CPAN.

The focus is on elements of style which are visible to the users of a module, rather than those parts which are only seen by the module's developers. However, many of the guidelines presented in this document can be extrapolated and applied successfully to a module's internals.

This document differs from perlnewmod in that it is a style guide rather than a tutorial on creating CPAN modules. It provides a checklist against which modules can be compared to determine whether they conform to best practice, without necessarily describing in detail how to achieve this.

All the advice contained in this document has been gleaned from extensive conversations with experienced CPAN authors and users. Every piece of advice given here is the result of previous mistakes. This information is here to help you avoid the same mistakes and the extra work that would inevitably be required to fix them.

The first section of this document provides an itemized checklist; subsequent sections provide a more detailed discussion of the items on the list. The final section, "Common Pitfalls", describes some of the most popular mistakes made by CPAN authors.

#QUICK CHECKLIST

For more detail on each item in this checklist, see below.

#Before you start

• Don't re-invent the wheel

• Patch, extend or subclass an existing module where possible

• Do one thing and do it well

• Choose an appropriate name

• Get feedback before publishing

#The API

• API should be understandable by the average programmer

• Simple methods for simple tasks

• Separate functionality from output

• Consistent naming of subroutines or methods

• Use named parameters (a hash or hashref) when there are more than two parameters

#Stability

• Ensure your module works under use strict and -w

• Stable modules should maintain backwards compatibility