Previous Page
Next Page

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]

    Previous Page
    Next Page