At a minimum, each file should have:
1. A one sentence explanation of what the code in the file does
2. The name of the author
3. A date
4. Some sort of copyright

Some sort of version is also important, but often this comes from an external revision control system.

The most important code comments explain the known defects, limitations and the problems in your code.

Comments tend to say what you hoped your program would do. Just when you need the comment the most, it lies!

When I am tempted to write a comment to explain something, I try to reformulate the comment into an error message. I use something like the or die idiom used when opening files. This gives me nice a spot to put my description of what is going on. It is also easier to maintain. If the this doesn't seem natural, I put in a diagnostic print statement with a trailing if $verbose.

something_tricky() or die "Failed to execute the trick";
print "So far I have $my_intermediate_result" if ($verbose > 0);

[download]

It should work perfectly the first time! - toma

In reply to Re: Too much documentation? by toma
in thread Too much documentation? by melguin

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.