Perl编程格式指南.doc

Perl编程格式指南名称P5EEx::Blue::perlstyle-P5EE样式指导P5EE是Perl5EnterpriseEnvironment(企业型Perl5样式指导）的缩写。介绍在P5EE发行版中,包含的所有代码和文件都遵循了本文所述的样式。请注意：这些样式并不是要抑制你的创造力，而是想要使那些阅读到你代码的家伙们的生活变得更容易一些。他也可以用来解决分歧，避免个人间纠纷。下面的这些约定适用于perl模块，web程序（CGI/mod_perl）以及命令行程序。当然，这些规则也在一定程度上适用于用P5EE写的perl代码。注意，这些都是指导性的方针，不是必须遵守的规则。如果在这里你真的需要违反其中一条的话，无论如何，最好先问问P5EE核心团队。另外，本文档中的大部分，并不是强调正确的方法就是我们的方法。我们需要有一些约定来让每个人的生活更容易一些。如果你有什么问题，可以在P5EE开发邮件列表中询问，[e-mail]://lists.perl.org/showlist.cgi?name=p5eeP5EE项目所需文件在下面这些网站上可以找到。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版本号是开发版本。例如：1.0.0P5EE1的首发版1.0.1P5EE1.0的第二次发布版1.0.10P5EE1.0的第二次发布版的第一次修正版1.1.0P5EE1.1的首发版2.0.0P5EE2的首发版版本号后面也可以跟一个连字符和一些文字，来表示特别的版本，或者给出额外的信息。例如1.1.4-bender注意，这是一个狂欢版1.5.0-pre1注意这不是最后的版本，而是预览版。在perl5.6.0中，你可以使用象v2.0.0这样的版本，但是在前几版的perl是不允许的。所以要把一个tuple版本号转换成一个用$VERSION表示的版本号字符串，使用正常的整数来表示主修订号，三个数字来做版本号和三个数字来做子版本号。例如：1.1.6->1.0010062.0.0->2.000000这样，perl就可以通过大于和小于比较两个版本字符串。LinuxForum中有一篇关于软件发行惯例的中文译版：http://www.linuxforum.net/books/srp/Software-Release-Practice-HOWTO