The excuse I hear over and over from programmers who don't write POD, don't write tests, and write incomprehensible code that they can include comments and everything will be OK.

Comments should be the item of last resort. For figuring out what code does, writing clear, concise code is first, followed by Pod, then unit tests and as a last resort, comments.

The reason for doing this in this order,

  1. Comments have no relation to how code runs. You can never be sure it is accurate and because they are never publicly (re)viewed, they can easily be ignored when doing updates.
  2. Unit tests do two things, test the validity of your code, and give a working example of how it is used. While it does not declare a context the code is supposed to be used, you should be able to write a proof of concept using tests.
  3. Pod is documentation that programmers will depend on to use your code. If your Pod is invalid, people will let you know or they stop using your code. It is harder to ignore Pod if you expect people to use code.
  4. Code should be first because it is the one thing that is ALWAYS done. Code is not simply a way of executing a particular action, it is instructions to tell the programmer HOW it is supposed to do it.

    If your code is so abstract that people cannot understand it, you have created a Rube Goldberg Machine that cannot be updated easily and will eventually end up being disgarded by something that can.

The one thing I believe in is documentation, just not half-hearted attempts by calling them 'comments.'

In reply to Re^5: Easily catalog subroutines with a synopsis comment by Herkum
in thread Easily catalog subroutines with a synopsis comment by blogical

Title:
Use:  <p> text here (a paragraph) </p>
and:  <code> code here </code>
to format your post, it's "PerlMonks-approved HTML":


  • Posts are HTML formatted. Put <p> </p> tags around your paragraphs. Put <code> </code> tags around your code and data!
  • Titles consisting of a single word are discouraged, and in most cases are disallowed outright.
  • Read Where should I post X? if you're not absolutely sure you're posting in the right place.
  • Please read these before you post! —
  • Posts may use any of the Perl Monks Approved HTML tags:
    a, abbr, b, big, blockquote, br, caption, center, col, colgroup, dd, del, details, div, dl, dt, em, font, h1, h2, h3, h4, h5, h6, hr, i, ins, li, ol, p, pre, readmore, small, span, spoiler, strike, strong, sub, summary, sup, table, tbody, td, tfoot, th, thead, tr, tt, u, ul, wbr
  • You may need to use entities for some characters, as follows. (Exception: Within code tags, you can put the characters literally.)
            For:     Use:
    & &amp;
    < &lt;
    > &gt;
    [ &#91;
    ] &#93;
  • Link using PerlMonks shortcuts! What shortcuts can I use for linking?
  • See Writeup Formatting Tips and other pages linked from there for more info.