perlmodstyle - 云端在线

程序：

您的姓名

perlmodstyle - Perl 模块风格指南

引言

本文档试图描述 Perl 社区编写 Perl 的“最佳实践”
模块。 它扩展了 perlstyle 中的建议，应该考虑
在阅读本文档之前需要阅读。

虽然本文档旨在对所有模块作者有用，但它特别
面向希望在 CPAN 上发布模块的作者。

重点是对模块用户可见的样式元素，而不是
那些只有模块开发人员才能看到的部分。 然而，许多
本文档中提供的指南可以外推并成功应用于
模块的内部结构。

本文档与 perlnewmod 的不同之处在于它是一个风格指南而不是一个教程
关于创建 CPAN 模块。 它提供了一个检查表，可以用来比较模块
确定它们是否符合最佳实践，而不必在
详细说明如何实现这一点。

本文档中包含的所有建议均来自广泛的对话
与经验丰富的 CPAN 作者和用户。 这里给出的每一条建议都是结果
之前的错误。 此信息旨在帮助您避免同样的错误和
修复它们不可避免地需要额外的工作。

本文件的第一部分提供了一个逐项核对清单； 后续章节
对清单上的项目进行更详细的讨论。 最后一部分，“共同
陷阱”，描述了 CPAN 作者犯的一些最常见的错误。

快 核对表

有关此清单中每个项目的更多详细信息，请参见下文。

申请早于 开始
· 不要重新发明轮子

· 在可能的情况下修补、扩展或子类化现有模块

· 做好一件事并做好

· 取一个合适的名字

· 发布前获取反馈

- API
· API 应该是普通程序员可以理解的

· 简单任务的简单方法

· 将功能与输出分开

· 子程序或方法的一致命名

· 当有两个以上的参数时使用命名参数（散列或散列引用）

稳定性
· 确保你的模块在“use strict”和“-w”下工作

· 稳定的模块应该保持向后兼容性

文件记录
· 在 POD 中编写文档

· 记录目的、范围和目标应用

· 记录每个可公开访问的方法或子程序，包括参数和返回
价值观

· 给出在你的文档中使用的例子

· 提供 README 文件，也许还提供发行说明、变更日志等

· 提供更多信息的链接（URL、电子邮件）

发布 注意事项
· 在 Makefile.PL 或 Build.PL 中指定先决条件

· 用“use”指定Perl版本要求

· 在你的模块中包含测试

· 选择合理且一致的版本编号方案（X.YY 是常见的 Perl
模块编号方案）

· 每次更改都增加版本号，无论多小

· 使用“make dist”打包模块

· 选择合适的许可证（GPL/Artistic 是很好的默认设置）

之前 您 主页 写作 A 模块

尽量不要在没有花一些时间思考的情况下贸然开始开发你的模块
第一的。 稍微深思熟虑可能会为您节省大量的精力。

有 it 很 完成 之前？
您甚至可能不需要编写模块。 检查是否已经在 Perl 中完成，
除非你有充分的理由，否则避免重新发明轮子。

寻找预先存在的模块的好地方包括http://search.cpan.org/>和
并询问“[电子邮件保护]"
(<http://lists.perl.org/list/module-authors.html>）。

如果现有模块 几乎 做你想做的事，考虑写一个补丁，写一个
子类，或以其他方式扩展现有模块而不是重写它。

Do 一种 事 和 do it 好
冒着显而易见的风险，模块旨在模块化。 Perl 开发人员
应该能够使用模块将其应用程序的构建块放在一起。
但是，重要的是块的形状正确，并且开发人员
当他们只需要一个小块时，不应该使用大块。

你的模块应该有一个明确定义的范围，不超过一个句子。
您的模块可以分解为一系列相关模块吗？

不好的例子：

“FooBar.pm 提供了 FOO 协议和相关 BAR 标准的实现。”

好例子：

"Foo.pm 提供了 FOO 协议的实现。Bar.pm 实现了相关的 BAR
协议。”

这意味着如果开发人员只需要 BAR 标准的模块，他们不应该
也被迫为 FOO 安装库。

什么是 in a 名称？
确保尽早为模块选择合适的名称。 这将帮助人们
查找并记住您的模块，并使您的模块编程更加直观。

命名模块时，请考虑以下事项：

· 具有描述性（即准确描述模块的目的）。

· 与现有模块保持一致。

· 反映模块的功能，而不是实现。

· 避免开始一个新的顶级层次结构，特别是如果一个合适的层次结构已经
存在您可以放置​​模块的地方。

积极 反馈 before 出版
如果您之前从未将模块上传到 CPAN（即使您有），那么您是
强烈建议您获得有关 PrePAN 的反馈http://prepan.org>. PrePAN 是一个站点
致力于与其他 Perl 开发人员讨论 CPAN 模块的想法，是一个很棒的
新的（和有经验的）Perl 开发人员的资源。

您还应该尝试从已经熟悉模块的人那里获得反馈
应用程序域和 CPAN 命名系统。 类似模块或模块的作者
具有相似名称的可能是一个不错的起点，Perl Monks 等社区站点也是如此
<http://www.perlmonks.org>.

设计方案 AND 写作 你的 模块

模块设计和编码的注意事项：

至 OO or 而不去 至 哦？
你的模块可能是面向对象的（OO），也可能不是，或者它可能有两种接口
可用的。 每种技术都有利有弊，您在使用时应加以考虑
设计你的 API。

In Perl的 最棒的 行为准则 （版权所有 2004，由 O'Reilly Media, Inc. 出版），Damian Conway
提供了在确定 OO 是否适合您的问题时使用的标准列表：

· 正在设计的系统很大，或者可能会变大。

· 数据可以聚合成明显的结构，特别是如果有一个大的
每个聚合中的数据量。

· 各类数据聚合形成自然层次，方便使用
继承和多态。

· 您有一段数据，对其应用了许多不同的操作。

· 您需要对相关类型的数据执行相同的一般操作，但使用
根据应用操作的特定数据类型，略有不同
至。

· 很可能您以后必须添加新的数据类型。

· 数据片段之间的典型交互最好由运算符来表示。

· 系统各个组件的实现可能会发生变化
时间。

· 系统设计已经是面向对象的。

· 大量其他程序员将使用您的代码模块。

仔细考虑 OO 是否适合您的模块。 无偿对象
定向导致复杂的 API，这对于普通模块用户来说很难
了解或使用。

设计 您的 API
您的接口应该是普通 Perl 程序员可以理解的。 下列
指南可以帮助您判断您的 API 是否足够简单：

编写简单的例程来做简单的事情。
拥有大量简单的例程比几个单一的例程要好。 如果你的
例程会根据其论点显着改变其行为，这表明
你应该有两个（或更多）单独的例程。

将功能与输出分开。
以最通用的形式返回您的结果，并允许用户选择如何
使用它们。 最通用的形式通常是 Perl 数据结构，它
然后可用于生成文本报告、HTML、XML、数据库查询或其他任何内容
否则您的用户需要。

如果您的例程遍历某种列表（例如文件列表，或
数据库中的记录）您可以考虑提供回调，以便用户可以
依次操作列表的每个元素。 File::Find 提供了一个例子
使用它的“find(\&wanted, $dir)”语法。

提供合理的快捷方式和默认值。
不要要求每个模块用户都跳同样的圈子来实现一个简单的
结果。 您始终可以包含可选参数或例程以用于更复杂或
非标准行为。 如果您的大多数用户必须键入一些几乎相同的
当他们开始使用你的模块时的代码行，这是你应该做的标志
这种行为是默认的。 您应该使用默认值的另一个很好的指标是如果
您的大多数用户使用相同的参数调用您的例程。

命名约定
你的命名应该是一致的。 例如，最好有：

显示日（）；
显示周（）；
显示年（）；

比

显示日（）；
周显示（）；
显示_年（）；

这同样适用于方法名称、参数名称和任何其他
对用户可见（以及大多数不可见的东西！）

参数传递
使用命名参数。 使用这样的哈希更容易：

$obj->do_something(
名称 => "wibble",
类型 => "文本",
大小 => 1024,
);

...而不是像这样有一长串未命名的参数：

$obj->do_something("wibble", "text", 1024);

虽然参数列表可能适用于一个、两个甚至三个参数，但任何
模块用户很难记住更多的参数，模块也很难记住
作者来管理。 如果要添加新参数，则必须将其添加到
向后兼容性列表的末尾，这可能会成为您的列表
命令不直观。 此外，如果许多元素可能未定义，您可能会看到以下内容
没有吸引力的方法调用：

$obj->do_something(undef, undef, undef, undef, undef, 1024);

为具有它们的参数提供合理的默认值。 不要让你的用户
指定几乎总是相同的参数。

是在散列中传递参数还是在 hashref 中传递参数的问题在很大程度上是一个问题
个人风格。

使用以连字符（“-name”）开头或完全大写的哈希键
("NAME") 是旧版本 Perl 的遗物，其中普通的小写字符串
"=>" 操作符没有正确处理。 虽然一些模块保留大写
或出于历史原因或个人风格的连字符参数键，
大多数新模块应该使用简单的小写键。 无论你选择什么，成为
持续的！

严格 和 警告
您的模块应该在严格的 pragma 下成功运行，并且应该在没有
产生任何警告。 您的模块还应在适当的情况下处理污点检查，
尽管这在很多情况下会造成困难。

向后 兼容性
“稳定”的模块不应该在没有至少一个
漫长的过渡阶段和版本号的重大变化。

误差 处理 和 条未读消息
当您的模块遇到错误时，它应该执行以下一项或多项操作：

· 返回一个未定义的值。

· 设置 $Module::errstr 或类似的（“errstr”是 DBI 和其他
流行的模块； 如果你选择别的东西，一定要清楚地记录下来）。

· "warn()" 或 "carp()" 给 STDERR 的消息。

· "croak()" 仅当您的模块完全无法弄清楚该做什么时。 （“发牢骚（）”
是在模块中使用的“die()”的更好版本，它从以下位置报告其错误
来电者的视角。 有关“croak()”、“carp()”等的详细信息，请参见 Carp
有用的例程。）

· 作为上述的替代方案，您可能更喜欢使用 Error 抛出异常
模块。

可配置的错误处理对您的用户非常有用。 考虑提供一个选择
警告和调试消息的级别，将消息发送到单独文件的选项，
指定错误处理例程或其他此类功能的方法。 一定要默认所有
这些选项最常用。

记录 你的 模块

POD
您的模块应该包括针对 Perl 开发人员的文档。 你应该使用 Perl 的
用于一般技术文档的“普通旧文档”(POD)，尽管您可能
希望编写其他文档（白皮书、教程等）
格式。 您需要涵盖以下主题：

· 模块常见用途的概要

· 模块的目的、范围和目标应用

· 使用每个可公开访问的方法或子程序，包括参数和
返回值

· 使用示例

· 进一步信息的来源

· 作者/维护者的联系电子邮件地址

Perl 模块文档中的详细程度通常从不太详细到更详细
详细的。 您的 SYNOPSIS 部分应该包含一个最小的使用示例（也许作为
只需一行代码； 跳过不寻常的用例或大多数人不需要的任何东西
用户）； 描述应该从广义上描述你的模块，通常只是一个
几段； 模块例程或方法的更多细节、冗长的代码示例，或
其他深入的材料应在后续章节中给出。

理想情况下，稍微熟悉您的模块的人应该能够刷新他们的
内存没有点击“翻页”。 当您的读者继续阅读文档时，他们
应该逐渐获得更多的知识。

Perl 模块文档中推荐的部分顺序是：

· 姓名

· 概要

· 描述

· 一个或多个章节或小节提供了可用方法的更多细节和
例程和任何其他相关信息。

· 错误/警告/等

· 作者

· 也可以看看

· 版权和许可

将您的文档放在它记录的代码附近（“内联”文档）。 包括 POD
对于该方法的子程序正上方的给定方法。 这样更容易保持
文档是最新的，并避免必须将每段代码记录两次（一次在
POD 和一次在评论中）。

自述文件， 安装， 释放 笔记， 变更日志
您的模块还应包含一个 README 文件，描述该模块并提供指向
更多信息（网站、作者电子邮件）。

应该包含一个 INSTALL 文件，并且应该包含简单的安装说明。
当使用 ExtUtils::MakeMaker 时，这通常是：

perl 生成文件.PL
使
做测试
使安装

使用 Module::Build 时，这通常是：

perl 构建.PL
perl 构建
perl 构建测试
perl 构建安装

应该为您的软件的每个版本生成发行说明或变更日志
用与用户相关的术语描述用户可见的模块更改。

除非您有充分的理由使用其他格式（例如，使用的格式
在您的公司内），惯例是将您的变更日志文件命名为“变更”，并
遵循 CPAN::Changes::Spec 中描述的简单格式。

RELEASE 注意事项

版本 编号
版本号应该至少表明主要和次要版本，可能还有次要版本
发布。 主要版本是其中大部分功能已更改的版本，或
添加了哪些主要的新功能。 次要版本是其中少量
功能已添加或更改。 次要版本号通常用于
不影响功能的更改，例如文档补丁。

最常见的 CPAN 版本编号方案如下所示：

1.00，1.10，1.11，1.20，1.30，1.31，1.32

正确的 CPAN 版本号是一个浮点数，后面至少有 2 位数字
十进制。 您可以通过使用来测试它是否符合 CPAN

perl -MExtUtils::MakeMaker -le 'print MM->parse_version(shift)' 'Foo.pm'

如果您想发布模块的“beta”或“alpha”版本，但不希望 CPAN.pm
将其列为最近使用的常规版本号后面的“_”，后跟至少 2
数字，例如。 1.20_01。 如果您这样做，建议使用以下习语：

我们的 $VERSION = "1.12_01"; # 所以 CPAN 发行版将有
# 正确的文件名
我们的 $XS_VERSION = $VERSION; # 仅当您有 XS 代码时才需要
$VERSION = eval $VERSION; # 所以“使用模块 0.002”不会警告
# 下划线

使用这个技巧 MakeMaker 只会读取第一行，从而读取下划线，
而 perl 解释器将评估 $VERSION 并将字符串转换为
数字。 稍后将 $VERSION 视为数字的操作将能够这样做
不会引起关于 $VERSION 不是数字的警告。

永远不要在不增加
数字。 即使是一个单词的文档补丁也应该导致版本的更改
次要级别。

一旦选择，重要的是坚持你的版本方案，不要减少数量
的数字。 这是因为“下游”打包程序，例如 FreeBSD 端口系统，
以各种方式解释版本号。 如果你改变你的数字位数
版本方案，您可以混淆这些系统，以便它们获取您模块的版本
秩序，这显然是不好的。

先决条件
模块作者应该仔细考虑是否依赖其他模块，以及哪些
依赖的模块。

最重要的是，选择尽可能稳定的模块。 按优先顺序：

· 核心 Perl 模块

· 稳定的 CPAN 模块

· 不稳定的CPAN模块

· CPAN 不提供的模块

在您的先决条件中指定其他 Perl 模块的版本要求
Makefile.PL 或 Build.PL。

确保在 Makefile.PL 或 Build.PL 中指定 Perl 版本要求，并使用
“需要 5.6.1”或类似的。 请参阅 perlfunc 中“require”的“use VERSION”部分
细节。

测试
所有模块都应该在分发之前进行测试（使用“make disttest”），并且测试
安装模块的人也应该可以使用（使用“make test”）。 为了
Module::Build 您将使用“make test”等效的“perl Build test”。

这些测试的重要性与所谓的模块稳定性成正比。 一种
声称稳定或希望实现广泛使用的模块应遵守
尽可能严格的测试制度。

帮助您编写测试的有用模块（对您的开发过程或
你的时间）包括 Test::Simple、Carp::Assert 和 Test::Inline。 对于更精致的
测试套件有 Test::More 和 Test::MockObject。

包装
模块应使用标准打包工具之一进行打包。 目前你有
ExtUtils::MakeMaker 和更独立于平台的 Module::Build 之间的选择，
允许以一致的方式安装模块。 使用 ExtUtils::MakeMaker 时，
你可以使用“make dist”来创建你的包。 现有工具可帮助您构建
MakeMaker 友好风格的模块。 其中包括 ExtUtils::ModuleMaker 和 h2xs。 看
还有perlnewmod。

授权计划
确保您的模块具有许可证，并且它的全文包含在
分发（除非它很常见，并且许可证的条款不要求您
包括它）。

如果您不知道使用什么许可证，GPL 和艺术许可证下的双重许可
（与 Perl 本身相同）是个好主意。 请参阅 perlgpl 和 perlartistic。

COMMON 陷阱

重塑 这些因素包括原料奶的可用性以及达到必要粉末质量水平所需的工艺。 轮
CPAN 已经很好地为某些应用程序空间提供了服务。
一个例子是模板系统，另一个是日期和时间模块，还有很多
更多的。 虽然编写您自己的这些东西的版本是一种通过仪式，但请
仔细考虑 Perl 世界是否真的需要您发布它。

试 至 do 也有 许多
您的模块将成为开发人员工具包的一部分。 它本身不会形成
整个 工具包。 在您的代码成为整体之前，很容易添加额外的功能
系统而不是一组模块化构建块。

不当 文件
不要落入为错误的受众写作的陷阱。 您的主要受众是
至少对你的模块有一定了解的有一定经验的开发人员
应用程序域，谁刚刚下载了您的模块并希望开始使用它作为
尽快。

教程、最终用户文档、研究论文、常见问题解答等不适用于
模块的主要文档。 如果你真的想写这些，把它们作为子
文档，例如“My::Module::Tutorial”或“My::Module::FAQ”，并在
另请参阅主要文档的部分。

使用 onworks.net 服务在线使用 perlmodstyle