perlmodstyle.html
来自「perl教程」· HTML 代码 · 共 809 行 · 第 1/3 页
HTML
809 行
<?xml version="1.0" ?>
<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.0 Transitional//EN">
<html>
<head>
<!-- saved from url=(0017)http://localhost/ -->
<script language="JavaScript" src="../../displayToc.js"></script>
<script language="JavaScript" src="../../tocParas.js"></script>
<script language="JavaScript" src="../../tocTab.js"></script>
<link rel="stylesheet" type="text/css" href="../../scineplex.css">
<title>perlmodstyle - Perl module style guide</title>
<link rel="stylesheet" href="../../Active.css" type="text/css" />
<meta http-equiv="content-type" content="text/html; charset=utf-8" />
<link rev="made" href="mailto:" />
</head>
<body>
<script>writelinks('__top__',2);</script>
<h1><a>perlmodstyle - Perl module style guide</a></h1>
<p><a name="__index__"></a></p>
<!-- INDEX BEGIN -->
<ul>
<li><a href="#name">NAME</a></li>
<li><a href="#introduction">INTRODUCTION</a></li>
<li><a href="#quick_checklist">QUICK CHECKLIST</a></li>
<ul>
<li><a href="#before_you_start">Before you start</a></li>
<li><a href="#the_api">The API</a></li>
<li><a href="#stability">Stability</a></li>
<li><a href="#documentation">Documentation</a></li>
<li><a href="#release_considerations">Release considerations</a></li>
</ul>
<li><a href="#before_you_start_writing_a_module">BEFORE YOU START WRITING A MODULE</a></li>
<ul>
<li><a href="#has_it_been_done_before">Has it been done before?</a></li>
<li><a href="#do_one_thing_and_do_it_well">Do one thing and do it well</a></li>
<li><a href="#what_s_in_a_name">What's in a name?</a></li>
</ul>
<li><a href="#designing_and_writing_your_module">DESIGNING AND WRITING YOUR MODULE</a></li>
<ul>
<li><a href="#to_oo_or_not_to_oo">To OO or not to OO?</a></li>
<li><a href="#designing_your_api">Designing your API</a></li>
<li><a href="#strictness_and_warnings">Strictness and warnings</a></li>
<li><a href="#backwards_compatibility">Backwards compatibility</a></li>
<li><a href="#error_handling_and_messages">Error handling and messages</a></li>
</ul>
<li><a href="#documenting_your_module">DOCUMENTING YOUR MODULE</a></li>
<ul>
<li><a href="#pod">POD</a></li>
<li><a href="#readme__install__release_notes__changelogs">README, INSTALL, release notes, changelogs</a></li>
</ul>
<li><a href="#release_considerations">RELEASE CONSIDERATIONS</a></li>
<ul>
<li><a href="#version_numbering">Version numbering</a></li>
<li><a href="#prerequisites">Pre-requisites</a></li>
<li><a href="#testing">Testing</a></li>
<li><a href="#packaging">Packaging</a></li>
<li><a href="#licensing">Licensing</a></li>
</ul>
<li><a href="#common_pitfalls">COMMON PITFALLS</a></li>
<ul>
<li><a href="#reinventing_the_wheel">Reinventing the wheel</a></li>
<li><a href="#trying_to_do_too_much">Trying to do too much</a></li>
<li><a href="#inappropriate_documentation">Inappropriate documentation</a></li>
</ul>
<li><a href="#see_also">SEE ALSO</a></li>
<li><a href="#author">AUTHOR</a></li>
</ul>
<!-- INDEX END -->
<hr />
<p>
</p>
<h1><a name="name">NAME</a></h1>
<p>perlmodstyle - Perl module style guide</p>
<p>
</p>
<hr />
<h1><a name="introduction">INTRODUCTION</a></h1>
<p>This document attempts to describe the Perl Community's "best practice"
for writing Perl modules. It extends the recommendations found in
<a href="../../lib/Pod/perlstyle.html">the perlstyle manpage</a> , which should be considered required reading
before reading this document.</p>
<p>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.</p>
<p>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.</p>
<p>This document differs from <a href="../../lib/Pod/perlnewmod.html">the perlnewmod manpage</a> 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.</p>
<p>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.</p>
<p>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.</p>
<p>
</p>
<hr />
<h1><a name="quick_checklist">QUICK CHECKLIST</a></h1>
<p>For more detail on each item in this checklist, see below.</p>
<p>
</p>
<h2><a name="before_you_start">Before you start</a></h2>
<ul>
<li>
<p>Don't re-invent the wheel</p>
</li>
<li>
<p>Patch, extend or subclass an existing module where possible</p>
</li>
<li>
<p>Do one thing and do it well</p>
</li>
<li>
<p>Choose an appropriate name</p>
</li>
</ul>
<p>
</p>
<h2><a name="the_api">The API</a></h2>
<ul>
<li>
<p>API should be understandable by the average programmer</p>
</li>
<li>
<p>Simple methods for simple tasks</p>
</li>
<li>
<p>Separate functionality from output</p>
</li>
<li>
<p>Consistent naming of subroutines or methods</p>
</li>
<li>
<p>Use named parameters (a hash or hashref) when there are more than two
parameters</p>
</li>
</ul>
<p>
</p>
<h2><a name="stability">Stability</a></h2>
<ul>
<li>
<p>Ensure your module works under <code>use strict</code> and <a href="../../lib/Pod/perlrun.html#item__2dw"><code>-w</code></a></p>
</li>
<li>
<p>Stable modules should maintain backwards compatibility</p>
</li>
</ul>
<p>
</p>
<h2><a name="documentation">Documentation</a></h2>
<ul>
<li>
<p>Write documentation in POD</p>
</li>
<li>
<p>Document purpose, scope and target applications</p>
</li>
<li>
<p>Document each publically accessible method or subroutine, including params and return values</p>
</li>
<li>
<p>Give examples of use in your documentation</p>
</li>
<li>
<p>Provide a README file and perhaps also release notes, changelog, etc</p>
</li>
<li>
<p>Provide links to further information (URL, email)</p>
</li>
</ul>
<p>
</p>
<h2><a name="release_considerations">Release considerations</a></h2>
<ul>
<li>
<p>Specify pre-requisites in Makefile.PL or Build.PL</p>
</li>
<li>
<p>Specify Perl version requirements with <a href="../../lib/Pod/perlfunc.html#item_use"><code>use</code></a></p>
</li>
<li>
<p>Include tests with your module</p>
</li>
<li>
<p>Choose a sensible and consistent version numbering scheme (X.YY is the common Perl module numbering scheme)</p>
</li>
<li>
<p>Increment the version number for every change, no matter how small</p>
</li>
<li>
<p>Package the module using "make dist"</p>
</li>
<li>
<p>Choose an appropriate license (GPL/Artistic is a good default)</p>
</li>
</ul>
<p>
</p>
<hr />
<h1><a name="before_you_start_writing_a_module">BEFORE YOU START WRITING A MODULE</a></h1>
<p>Try not to launch headlong into developing your module without spending
some time thinking first. A little forethought may save you a vast
amount of effort later on.</p>
<p>
</p>
<h2><a name="has_it_been_done_before">Has it been done before?</a></h2>
<p>You may not even need to write the module. Check whether it's already
been done in Perl, and avoid re-inventing the wheel unless you have a
good reason.</p>
<p>Good places to look for pre-existing modules include
<a href="http://search.cpan.org/">http://search.cpan.org/</a> and asking on <a href="mailto:modules@perl.org">modules@perl.org</a></p>
<p>If an existing module <strong>almost</strong> does what you want, consider writing a
patch, writing a subclass, or otherwise extending the existing module
rather than rewriting it.</p>
<p>
</p>
<h2><a name="do_one_thing_and_do_it_well">Do one thing and do it well</a></h2>
<p>At the risk of stating the obvious, modules are intended to be modular.
A Perl developer should be able to use modules to put together the
building blocks of their application. However, it's important that the
blocks are the right shape, and that the developer shouldn't have to use
a big block when all they need is a small one.</p>
<p>Your module should have a clearly defined scope which is no longer than
a single sentence. Can your module be broken down into a family of
related modules?</p>
<p>Bad example:</p>
<p>"FooBar.pm provides an implementation of the FOO protocol and the
related BAR standard."</p>
<p>Good example:</p>
<p>"Foo.pm provides an implementation of the FOO protocol. Bar.pm
implements the related BAR protocol."</p>
<p>This means that if a developer only needs a module for the BAR standard,
they should not be forced to install libraries for FOO as well.</p>
<p>
</p>
<h2><a name="what_s_in_a_name">What's in a name?</a></h2>
<p>Make sure you choose an appropriate name for your module early on. This
will help people find and remember your module, and make programming
with your module more intuitive.</p>
<p>When naming your module, consider the following:</p>
<ul>
<li>
<p>Be descriptive (i.e. accurately describes the purpose of the module).</p>
</li>
<li>
⌨️ 快捷键说明
复制代码Ctrl + C
搜索代码Ctrl + F
全屏模式F11
增大字号Ctrl + =
减小字号Ctrl + -
显示快捷键?