Perl 最佳实践(节选) --- 07

第七章：说明文档

零捌肆.

区分用户说明文档和技术说明文档。

零捌伍.

替模块和应用程序创建标准POD模板。

零捌陆.

把你的标准POD模板予以扩展和自定义。

零捌柒.

在源代码文件中放置用户说明文档。

零捌捌.

把所有用户说明文档放在源代码文件中的单独的地方。

零捌玖.

尽可能把POD放在靠近文件末尾处。

零捌肆.

对技术说明文档做适当的细化。

零玖零.

主要注释应使用块模板。

零玖壹.

使用整行注释来说明算法。

零玖贰.

使用行尾注释来指出微妙之处和奇怪之处。

零玖叁.

对任何让你困惑或受骗的东西都要做注释。

零玖肆.

考虑改写是否比做注释更好。

零玖伍.

较长的技术讨论内容要使用“看不见”的POD段落。

零玖陆.

检查说明文档的拼写、语法以及健全性。