Beefy Boxes and Bandwidth Generously Provided by pair Networks
P is for Practical
 
PerlMonks  

Comment on

( #3333=superdoc: print w/replies, xml ) Need Help??

People have already written that one should comment, but i would like to make an addendum to that:
Comment well.

Bad comments are worse than no comments at all. Some areas need heavy commenting because they do the black magic of the program. In these cases, it's usually better to type up a well-written paragrah (in full english) that explains why the section does what it does and how. Then post that paragraph above the black magic and make sure it's noticeable and easy to read (using various commenting styles to make it obviously important)

As a general rule of thumb, if you can't comment it well you might reconsider how you're approaching the problem that the code solves. i've had to reinvent a code section three or four times on one program just because i couldn't describe why i did it that way that made any sense.

And lastly, to make sure that beautiful paragrah makes sense, see if a co-worker or pedestrian (hopefully with no knowledge of that section fo the program) can read and understand what you're trying to do. If they can, then when you go back and read it 2 days later, you should also have no problems.

This is just my experience, YMMV, HTH,
jynx

PS If it takes more than a paragraph to describe some code, maybe you're doing too much with that section, it might needs be split up, maybe...


In reply to Re: How to write long programms? by jynx
in thread How to write long programms? by pokemonk

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, 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, 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.
  • Log In?
    Username:
    Password:

    What's my password?
    Create A New User
    Chatterbox?
    [Corion]: Hmmm. I feel a Meditation coming on. I wrote a module, DBIx::PivotQuery, which returns a table-like set of rows (AoA) but some columns are generated from column values, like in an (Excel) pivot table or a ROLLUP command
    [Corion]: My current approach for subtotals involves rerunning the given query, with the hint to the user that they should use a temporary table if they want better performance.
    [Corion]: But I could create that temporary table in the module and use it for the improved perfomance directly instead.
    [Corion]: And the question is, what would be better/preferred ;-)
    [Corion]: Hmm - not exactly like the ROLLUP command. Ah well.

    How do I use this? | Other CB clients
    Other Users?
    Others chilling in the Monastery: (10)
    As of 2017-02-23 15:24 GMT
    Sections?
    Information?
    Find Nodes?
    Leftovers?
      Voting Booth?
      Before electricity was invented, what was the Electric Eel called?






      Results (347 votes). Check out past polls.