Beefy Boxes and Bandwidth Generously Provided by pair Networks
Just another Perl shrine

Comment on

( #3333=superdoc: print w/replies, xml ) Need Help??
One, I have a rule I teach to any programmer under my supervision: strategy in comments, tactics in code. Tactics are what you do to get something done. Strategy explains what you want done. In warfare, an officer focuses on strategy: "secure that hill!" "pick the best two devices!" "find the local minimum!" Don't mention the tools you use to get that job done, soldier, unless you're being fiendishly clever. Comments should be in natural human language, while the code should just accomplish those tasks.

Two, I have a technique I teach to any new programmer, whether they're under my supervision or not: write the comments first. Programming courses always talk about writing pseudocode: why write it on scratch paper, just to throw it away?

sub process_ring_packet { # if we have a prior server registered, # if this packet was received from the prior, # if this server created this packet originally, # kill the packet, it's completed the trip. # scan the packet for all object references. # dispatch packet to object mentioned which we control. # if any object references remain unhandled, # if we have a next server registered, # send the packet to the next server. }
Once the pseudocode is written in human terms, then fill in your actual code in whatever computer language is being employed. Note that I didn't say HOW to do each of the tasks in the comments. I just wrote what needed to get done.

Lastly, as others have indicated, the actual code should not be too clever for your teammates to understand at a glance. Use clear concise words for variable names, without abbreviating them unnecessarily. Use the idioms they're familiar with. Use the language they're familiar with. You shouldn't need any # swap $x and $y comments to explain basic tasks or idioms. If you really find a clever but unusual trick, or you need to hack out something that's not obvious, then you can mention it.

I have taught my editors to highlight tags like #REVIEW: #TODO: #BUGBUG: #HACK: so I can see areas that need more attention. Review things which may or may not be right or done in the best way. List things that are definitely undone but needed. Mark areas where known bugs are located, even if the fix isn't in there yet; give bug tracking numbers if appropriate. Mark code which is overly clever to get around dumb library limitations or which save a lot of processing in obscure ways.

[ e d @ h a l l e y . c c ]

In reply to Strategy in Comments, Tactics in Code by halley
in thread The art of comments: (rave from the grave) by BrowserUk

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?

    What's my password?
    Create A New User
    [Lady_Aleena]: Hello Discipulus, Corion, choroba, and marioroy...
    [Corion]: Hi Lady_Aleena!
    [Lady_Aleena]: marioroy, are you also writing a Meditation for this?
    choroba o/
    Discipulus adds tozzetti alle mandorle to the platter on the sideboard.
    Lady_Aleena was checking #cbstream and saw the big announcement.
    [marioroy]: Tie::IxHash can be shared. Also similar modules. I cannot wait to post a solution sharing Tie::File and iterating among workers.
    [marioroy]: Lady_Aleena Yes, will post something with all the new features. Parallel with few lines of code.
    [marioroy]: Yes, will do for PM. I love PM.
    Lady_Aleena ponders a meditation of her own, but it would be on a far far less important topic.

    How do I use this? | Other CB clients
    Other Users?
    Others cooling their heels in the Monastery: (7)
    As of 2017-05-26 08:52 GMT
    Find Nodes?
      Voting Booth?