If you look across some modules like CGI
and some other standard ones, you will notice that they have that exact same commenting style.
I bought a C++ book recently and it stated that comments may or may not be good because people might not update them and it will confuse you later. So it is at the choice of the user. In this case, it is what happened to you.
Personally, I don't comment much. I find that it doesn't help me unless I have some really complex code. Usually I have helpful variable, subroutine, and script names that will help me along my path and most of the time my code isn't too complex anyway :).
Overall, that commenting style seems to be the best decision from what I know because you might change the order or names of variables but the functionality still remains the same so the comment will never need to be changed. Thus, preventing confusion and bad comments.
I just noticed Iwas a little vaque in my answer. By "That commenting style" I meant like the subroutine (s)he showed above.
print chr($_-39); # Easy but its ok.
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.
| & || & |
| < || < |
| > || > |
| [ || [ |
| ] || ] ||