注释常规代码注释常规代码很容易。如果可能，只要将注释对齐，尽量简练，当事情不清楚时，不要害怕深入解释它们。
清单 9
1
2
3
4
5
6
7
8
9
| print Dumper \%ENV; # print the full ENV hash
# get the environment variable names that begin with USER
@user_vars = grep(/^USER/, keys %ENV);
# print the values in all the variables that begin with USER, using a
# hash slice
print Dumper @ENV{@user_vars};
print "Done\n"; # print "done" message
# TODO: find better method of sorting variables
# TODO: use Data: umper with variable names
|
请注意，注释从第 0 列或第 40列开始。一致性使注释更具可读性。同样，必要时，多行注释会更好。还可以使用注释来记录在哪里发生了功能丢失、错误或不完整。如果想遍历所有代码并且查看还有哪些东西不完整，则“TODO”字很有用— 一个快速的 grep 命令将打印出所有 TODO 项。
不必注释每行代码，但是，请记住当调试或扩展程序时，注释是一种最好的资源。任何其它来源的程序员文档往往落后于实际代码，除非程序员非常勤奋。
注释循环和条件语句应该象注释常规代码和函数一样注释循环和条件语句。对循环编号以便以后标识它们似乎有些过分。更好的方法是使用折叠编辑器，折叠循环时，它可以将整个循环显示成一行（折叠标记之间的行是隐藏的，但它们仍然存在）。考虑一下如XML/HTML开始／结束标记这样的折叠的标记，它们是可以嵌套的。您最喜爱的编辑器可能已经支持折叠。(X)Emacs就支持折叠，它不是使用 Outline 就是使用 folding.el 方式。
清单 10
1
2
3
4
5
6
| # go through all the numbers between 2 and 200, and print a message
# for each one
foreach my $counter (2 .. 200)
{
print "Whoa, the counter is $counter!\n";
}
|
总是陈述循环的目的和边界。例如，“count from 2 to200”很好，但是“processarray”则不好。如果逻辑条件影响边界，同样陈述它们，但不在循环的顶部。循环顶部的摘要不应该记录常规迭代的异常，除非它们对循环非常重要。您自己判断吧。
注释程序的最终阶段在许多方面，程序的结尾是最繁琐的。工作已经完成，数据结构已经进入休眠状态（在Perl中不必担心内存释放），并且现在离结尾只差几行了。不要让这愚弄了您 —程序的结束行可能与其它行一样危险。在这里，注释最不起眼的行，因为调试程序员所做的第一件事就是查看程序的退出行为。
清单 11
1
2
3
4
5
6
7
| # delete old files, warn if they can't be removed
foreach (@myfiles)
{
unlink $_ or warn "Couldn't remove $_: $!";
}
print "whodunit.pl is done!\n"; # tell the user we're done
exit; # exit peacefully
|
编写程序的 POD文档和帮助旧式纯文档（Plain old documentation (POD)）是将 Perl脚本放入脚本本身的一种方法。 perldoc perlpod 命令将告诉您有关 POD 文档及其语法的更多信息。好的 POD文档意味着用户可以快速和有效地访问程序的帮助。花时间学习 POD语法：编写手册将更容易。另外，POD与各种手册格式化程序兼容，因此可以从同一文档生成一个纯文本文件、UNIX风格的帮助手册页和专业 LaTeX 文件。POD是一个十分有限的格式，但是足够满足大多数文档的需要。
通常，下列节应该出现在 POD文档中：NAME、SYNOPSIS、DESCRIPTION、OPTIONS、RETURNVALUE、ERRORS、DIAGNOSTICS、EXAMPLES、ENVIRONMENT、FILES、CAVEATS/WARNINGS、BUGS、RESTRICTIONS、NOTES、SEEALSO、AUTHORS 以及 HISTORY（从 perldoc pod2man 中可以找到有关每节的更多信息；请记住这些是建议而不是命令）。
某些程序员对其程序设置 -h 开关以对程序调用perldoc，因此打印出 POD 文档，就象用户输入 perldocwhodunit.pl 一样。这里的问题是用户不想从 -h 开关获取更多的额外信息。他只想要选项的摘要和列表。因此，更好的方法是编写从使用 -h 开关产生的单独帮助处理程序。
清单 12
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
| # print_help: help handler, prints out help for whodunit.pl and exits
sub print_help
{
# print the help itself
print << EOHIPPUS;
This is help for the whodunit.pl program.
You can pass options to whodunit.pl as command-line arguments. For
example:
..../whodunit.pl -h
..../whodunit.pl -show suspects
List of options:
-h : print this help
-show : show the suspects, victims, or detectives (all of them if no
second argument is specified)
-quiet : print no information other than the killer's name
EOHIPPUS
exit; # do nothing else, just exit quietly
}
|
请注意 print_help 文档本身。POD文档和其它联机帮助的外观同样也很重要。用户首先看的不是手册。使用 -h 标志或者查看 POD文档会方便得多。注意冒号的对齐、行之间的空格和整体整洁。表面的外观往往比程序提供的实际功能更重要。编写得好的程序首要的是应该具有良好的文档。
某些程序员喜欢在程序中包含 POD 文档来代替常规注释。这样的 POD注释自己用某行上的 =pod 开头（还有其它选项，在 perlpod文档中解释），并且自己以 =cut 在某行结束。 =pod 行告诉 Perl编译器停止解释每件事，直到 =cut 行为止，事实上从脚本本身排除了那个文本块。如果用户也是程序员，这当然好，但是如果普通用户只想查看脚本的文档而不是代码本身的注释，这可能会把他们弄糊涂。这个方法还将文档散布在整个代码中。应该限制它的使用。 |
