Beefy Boxes and Bandwidth Generously Provided by pair Networks
"be consistent"

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
    and all is quiet...

    How do I use this? | Other CB clients
    Other Users?
    Others having an uproarious good time at the Monastery: (5)
    As of 2017-11-24 23:01 GMT
    Find Nodes?
      Voting Booth?
      In order to be able to say "I know Perl", you must have:

      Results (354 votes). Check out past polls.