targetsmart:

Your code should be written to be as clear as possible, as it's supposed to adequately explain *what* it does. Normally, the types of comments I use are:

  1. Section breaks to show when I'm "shifting gears" in the code. (Such as "Initialization section", "Process results", "Print reports". These aren't really necessary, but I find them a handy way to segue between sections.)
  2. References to algorithms I intended to implement, if they're unusual. These will normally be in the comment header for the function.
  3. Specific and implied business requirements. This is the most important type of comment in my view. Business logic and programmer logic are quite different at times, so code that looks obviously wrong can be correct and vice versa. If the line of business specifies that you define "Gross Annual Sales" as the number of items you sold last Tuesday, then that's what you have to deliver. (No matter how Marketingesque the logic is.) Implicit requirements are also important--these are the ones where you have to work around flaws in other subsystems or business processes.
  4. Assumptions I'm making for input. (Gee, I assume that all our products are *heavier* than 0kg. I hope we don't start selling Helium balloons or this routine will break!)

Of course, commenting styles are varied, so this list is strictly my opinion...

...roboticus

In reply to Re: Why no comments? by roboticus
in thread Why no comments? by targetsmart

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.