use Perl

• Two different purposes (Score:1)

  by LTjake (4001)

  pod and "#" comments serve two distinct purposes.
  
  pod is for API documentation, usage examples, links (see also, websites, etc).
  
  regular "#" comments are there to let the programmer know what is going on in a particular part of the code (see this perlbuzz post for examples: http://perlbuzz.com/mechanix/2007/12/how-to-document-your-code.html [perlbuzz.com])
  
  HTH.
  • Re: (Score:1)

    by Aristotle (5147)

    What he said.

    In short, POD is for the guy who uses the code, whereas comments are for the guy who maintains it.
    • Re: (Score:1)

      by sigzero (5768)

      ding ding ding
      
      I get it now
• What vs Why (Score:1)

  by Alias (5735)

  POD describes for other users WHAT the code does.
  
  Comments describe for other maintainers WHY the code does it.
• POD Alternative (sortof) (Score:1)

  by renodino (6856)

  Pod::Classdoc [presicient.com] is something I whipped up after trying to provide API docs for a major project, and finding the usual POD format sorely lacking. Its POD, but of a Javadocish nature. Intended as an adjunct to "user Guide" type POD.