I know this is a very late response to a now-old node, but I want to add that commenting code using #comments is less useful than documenting code using =pod / =cut slices. I just picked up the habit of putting all major information into POD and I'm loving it.

This way my subs (or packages) can sit in fully-documented separate files and if I need to know something I don't have to sort through the code to learn find it, perldoc package_name.pl gets me to the information I need very quickly (this is basically an echo of Tilly's comment about documenting the interface). Storing the libraries as libraries (instead of putting all the code in a single file) during development means that the POD in the packages does not interfere with the POD for the main script-- this also means that I can share my package with others easily, since the docs are already written. Sometimes # is good for short notes, but for longer notes, you can always use POD tag like =note to make notes that don't show up in the normal course of POD parsing.