Perl Best Practices

Chapter 7. Documentation

Documentation is like sex: when it's good, it's very, very good; and when it's bad, it's still better than nothing.

—Dick Brandon

Documentation: for most development programmers it's a millstone, but for maintenance programmers it's a life-line. More importantly, very few programmers are exclusively in one role or the other. Most developers write code that they then have to maintain themselves. Or else they have to maintain other people's code in order to develop their own.

The problem is that any code of your own that you haven't looked at for six or more months might as well have been written by someone else ^[33]. The young, smart, optimistic you—who's creating the code—will undoubtedly find it tedious to document your understanding of what that code does and how it does it. But the older, wiser, sadder you—who later has to fix, extend, and adapt that code—will treasure the long-forgotten insights that your documentation preserves.

In that sense, documentation is a love letter that you write to your future self.

Types of Documentation

Distinguish user documentation from technical documentation.

End users will rarely read your code, or your comments. If they read anything at all, they'll run your module or application through perldoc^[34] and read whatever emerges.

On the other hand, maintainers and other developers may also read your POD^[35], but they'll spend far more of their time looking directly at your code.

So it makes sense to put user documentation in the ...