Perl Best Practices [Electronic resources] نسخه متنی

B.6. Chapter 7, Documentation

• Distinguish user documentation from technical documentation. [Types of Documentation ]

• Create standard POD templates for modules and applications. [Boilerplates ]

• Extend and customize your standard POD templates. [Extended Boilerplates ]

• Put user documentation in source files. [Location ]

• Keep all user documentation in a single place within your source file. [Contiguity ]

• Place POD as close as possible to the end of the file. [Position ]

• Subdivide your technical documentation appropriately. [Technical Documentation ]

• Use block templates for major comments. [Comments ]

• Use full-line comments to explain the algorithm. [Algorithmic Documentation ]

• Use end-of-line comments to point out subtleties and oddities. [Elucidating Documentation ]

• Comment anything that has puzzled or tricked you. [Defensive Documentation ]

• Consider whether it's better to rewrite than to comment. [Indicative Documentation ]

• Use "invisible" POD sections for longer technical discussions. [Discursive Documentation ]

• Check the spelling, syntax, and sanity of your documentation. [Proofreading ]