Beefy Boxes and Bandwidth Generously Provided by pair Networks
The stupid question is the question not asked
 
PerlMonks  

comment on

( #3333=superdoc: print w/replies, xml ) Need Help??
The main things I like about these types of comments are that they allow the reader to determine ...

- Assumptions that the routine makes (e.g. a resource is locked by the caller before the routine is called; the routine isn't called very often so performance is not important and the implementation is simplified). Obviosly, you'll want to put in assertion-like sanity checks to handle these whenever you can, but there are cases where this is not possible and these may be buried (hence obfuscated) in the code.

- Limitations of the implementation and future changes that could be made. Many times this is something like an idea of how to improve performance (i.e. by introducing some complexity) if an assumption changes about how the routine will be used in the future.

Unfortunately, some project management types who believe that "more == better" get real pedantic and start mandating that all sorts of useless drivel appear here that is either quickly outdated and/or can be gleaned from the first two lines of the sub.

bluto


In reply to Re: flower box comments by bluto
in thread flower box comments by mandog

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?
    and the web crawler heard nothing...

    How do I use this? | Other CB clients
    Other Users?
    Others cooling their heels in the Monastery: (5)
    As of 2019-10-18 03:41 GMT
    Sections?
    Information?
    Find Nodes?
    Leftovers?
      Voting Booth?
      Notices?