Perl 编程格式指南

名称P5EEx::Blue::perlstyle - P5EE 样式指导 P5EE 是 Perl 5 Enterprise Environment (企业型 Perl5 样式指导）的缩写。 介绍在P5EE发行版中,包含的所有代码和文件都遵循了本文所述的样式。请注意：这些样式并不是要抑制你的创造力，而是想要使那些阅读到你代

名称

P5EEx::Blue::perlstyle - P5EE 样式指导 P5EE 是 Perl 5 Enterprise Environment (企业型 Perl5 样式指导）的缩写。

介绍

在P5EE发行版中,包含的所有代码和文件都遵循了本文所述的样式。请注意：这些样式并不是要抑制你的创造力，而是想要使那些阅读到你代码的家伙们的生活变得更容易一些。他也可以用来解决分歧，避免个人间纠纷。 下面的这些约定适用于perl模块，web程序（CGI/mod_perl）以及命令行程序。当然，这些规则也在一定程度上适用于用P5EE写的perl代码。 注意，这些都是指导性的方针，不是必须遵守的规则。如果在这里你真的需要违反其中一条的话，无论如何，最好先问问P5EE核心团队。 另外，本文档中的大部分，并不是强调正确的方法就是我们的方法。我们需要有一些约定来让每个人的生活更容易一些。 如果你有什么问题，可以在P5EE开发邮件列表中询问，[email protected]. http://lists.perl.org/showlist.cgi?name=p5ee P5EE项目所需文件在下面这些网站上可以找到。 http://p5ee.perl.org/ http://www.officevision.com/pub/p5ee 本文档将随时间不断更新，每份最新的文档结尾，都会有历次版本的变动记录。

编码规则

Perl版本

我们是在perl5.005_03上编写所有代码的。也许有一天我们应该利用以下perl5.6的特性。不管怎样，所有代码应该在perl5.005_03以及后续版本上都能运行。P5EE所有的核心代码都在perl5.005_03和perl5.6.0上测试过，虽然现在P5EE用在perl5.6上比较多。

文档

所有的模块文档都应参照模块模板文件中的POD例子来撰写，解释模块的方法，目的，用途和每个带有名字，描述，输入，输出，受影响因素等信息的公用API。 文档中，如果需要返回一个数组或哈希表的引用，要记录数组的大小（包括恰当地描述每个元素都是什么）和哈希表中每个键的名字。如果是复合数据结构的话，尽量描绘出合适的结构。 另外，在文档中还要记录出返回数据是什么类型的数值。是整型，还是一段HTML代码，还是一个布尔值？ 所有命令行程序的选项都要使用命令行程序样本文件中的代码来记录。每个有效的方法，switch结构等等都要被记录，连同方法的描述，目的，程序如何使用。不要尝试对不同目的的程序使用相同的选项。 对于所有的WEB程序，应当在程序注释段中说明功能，目的和使用。 任何外部文档，命令行程序和模块的文档都要写成POD样式。这样的话，我们就可以把它们通过多种pod2xxx的转换器转换成各种格式的其他文档。POD不是一种正规的标签语言，它只是一种可以让文档非常容易转换成其他格式的方法。如果你有什么问题的话，可以自己看一下Perl自带的 perlpod帮助页 或者 询问我们及其其他懂POD的人。Perl中国推广组的FPC里面，也有一篇 [[fayland]] 所写的关于 [[如何撰写POD]] 的文章。

版本

分别使用模块，web程序，命令行程序样本文件中版本的代码。模块中的$VERSION将会反映出CVS的版本。Makefile.PL文件应该包含版本描述，并且还应该不依赖于CVS仓库中任何一个单独文件的版本。 同样，拥有$VERSION的XS模块也会反映出发行版的版本，否则每当你对文件做了一点改动，你都需要重新编译那些已经共享的库。这对于从事开发工作中的人来讲，的确是一种痛苦。 我们的发行版本号使用tuples模式，第一个数字是主修订号，第二个数字是版本号，第三个数字是子版本号。Odd-numbered版本号是开发版本。例如：