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

Comment on

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

I've never had to work with one of the legendary "comment every line" types -- it could be they don't get hired at the kind of places I've worked.

From skimming tilly's example here: [Text::xSV] I would summarize that he likes sparse, higher-level comments, but with very verbose error messages that actually function fairly well as substitutes for comments. At a glance it does seem that both variable names and sub names are a bit short, but then, they don't strike me as confusing. He also likes pod-at-the-bottom style which also comes recommended by Conway in his "Best Practices" (I'm a fan of interspersed-pod style, myself, but not so much that I'd insist it's the One True Way).

By the way: if the main objection to comments is that they tend to diverge from the code, what does one do about those rather infrequently run error messages? Don't they, too, tend to diverge from the code? And what about the the "=item" lists buried down in the pod?

Anyway, as it happens, I've written up a brief comment example: Re^5: Programming *is* much more than "just writing code". In summary: explaining a paragraph of code in english can speed skimming through the code, and hinting at how a line of code works can sometimes be a good idea.

In reply to Re^3: Code Maintainability by doom
in thread Code Maintainability by mpeever

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 making s'mores by the fire in the courtyard of the Monastery: (3)
    As of 2018-06-25 04:34 GMT
    Find Nodes?
      Voting Booth?
      Should cpanminus be part of the standard Perl release?

      Results (126 votes). Check out past polls.