hash variable names: possibly append _of if it makes things clearer:
$color_of{$widget} eq 'green'
documentation: POD and comments
use POD for interface notes and perl comments for implementation notes.
Inline or End of File (EOF)?
arbitrary choice, but decide beforehand for clarity.
Inline supports laziness: not bouncing around document to update POD
EOF supports clarity: docs possibly in different order than code.
possibly, end-user code should have EOF POD; modules for developers should have inline POD
If you're lucky, your editor will comment POD (cperl-mode in emacs)