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.
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:
You may need to use entities for some characters, as follows. (Exception: Within code tags, you can put the characters literally.)
- 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
Link using PerlMonks shortcuts! What shortcuts can I use for linking?
See Writeup Formatting Tips and other pages linked from there for more info.
| & || & |
| < || < |
| > || > |
| [ || [ |
| ] || ] ||