Beefy Boxes and Bandwidth Generously Provided by pair Networks
Don't ask to ask, just ask
 
PerlMonks  

Comment on

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

No, for me, the comments didn't help make this more maintainable.

This is exactly why I often state the aphorism, strategy in comments, tactics in code. Write your comments to explain the intended overall goal of a snippet, not what each argument is or why you wrote it with that particular syntax. I nearly should be able to delete the CODE unseen and rewrite it to match the COMMENTS.

To help understand the difference between strategy and tactics, think of the Lieutenant or Line Manager: they order you to secure a rock, or to set camp, or to close the deal, or to collect the report. Unless they're ineffective micromanagers or they're training you, they don't mention the tools that you, the grunt/peon, will need to accomplish the job.

For code comments, I don't want to hear the word "array" or "regex," I already am familiar with those terms or you should fire me. Tell me that you want to generate the exhaustive set of printer model names, or the font's available glyph names, or the lexically scanned tokens, or whatever this is.

If you want comments to succeed, it should be legible in English (or whatever your maintenance coders will agree to read). Say it out loud, and imagine hearing someone say it to you. If something seems clumsy or vague, rephrase. Consider capitalization and punctuation to aid the reader.

Then reinforce your strategic comments with tactical code. Phrase the code so it reads naturally if possible, and reinforce the comments' value by sharing the key nouns as identifiers in the code.

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


In reply to Re: I wrote some clever code - can the comment "defuse" it? by halley
in thread I wrote some clever code - can the comment "defuse" it? by Aristotle

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!
  • 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
  • Outside of code tags, you may need to use entities for some characters:
            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?
    and the web crawler heard nothing...

    How do I use this? | Other CB clients
    Other Users?
    Others wandering the Monastery: (7)
    As of 2014-07-22 09:52 GMT
    Sections?
    Information?
    Find Nodes?
    Leftovers?
      Voting Booth?

      My favorite superfluous repetitious redundant duplicative phrase is:









      Results (109 votes), past polls