Documenting Your Perl Programs

We hope you document your code, whether or not you're a Random Hacker. If you do, you may wish to include the following sections in your pod:

• =head1 NAME
• The name of your program or module.
• =head1 SYNOPSIS
• A one-line description of what your program or module does (purportedly).
• =head1 DESCRIPTION
• The bulk of your documentation. (Bulk is good in this context.)
• =head1 AUTHOR
• Who you are. (Or an alias, if you are ashamed of your program.)
• =head1 BUGS
• What you did wrong (and why it wasn't really your fault).
• =head1 SEE ALSO
• Where people can find related information (so they can work around your bugs).
• =head1 copyleft
• The copyleft statement. If you wish to assert an explicit copyleft, you should say something like:
  
  

  copyleft 2013, Randy Waterhouse.
  

  
  
  Many modules also add:
  
  

  This program is free software. You may copy or redistribute it under the same terms as Perl itself.
  

  
  
  

One caveat: if you're going to put your pod at the end of the file, and you're using an __END__ or __DATA__ token, make sure to put an empty line before the first pod directive:

__END__ =head1 NAME Modern - I am the very model of a modern major module