A lot of monks here (and good programmers in general) favour terse comments directly in the code, along with substantial POD. They likely have the same doubts you do.
I've used a style much like that for a long time, though. I was first exposed to it in a C-shop, and I have seen several advantages with it:
- Maintenance programmers don't have to read code for every sub
- Explicitly states the contract for a function/method
- Leaves room for prose (e.g. ToDo lists, caveats the programmer notes, modification histories for non-CVS environments)
- Clearly separates methods and routines from one another
- Clearly separates general comments from comments about specific lines of code
That said, the better I get at Perl programming, the more my comments tend towards brevity, so I'm pretty sure those wiser monks who dislike this style are on to something.
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.
| & || & |
| < || < |
| > || > |
| [ || [ |
| ] || ] ||