The problem is that it's difficult to find the ideal comment. It's easier to discuss what makes a good comment, or what doesn't, than to find a file that contains all good comments.
It's much easier to come up with a contrived example, than to point to a file, and say 'the comments on lines 1873 to 1904 are great... of course, the rest of them suck'.
We can't easily link to modules or such on CPAN, as they're bound to change, and so when someone comes back and reads this thread a month from now, the links might make no sense.
If you're really in the mood for specific code -- I'll insert it here:
The thing is -- there's a mix of good and bad comments. There's stuff in there that I said was bad (redundant comments), there's stuff that Forsaken mentioned (writing the logic in comments, then fleshing out the code), there's end-user documentation in pod, there's comments hidden from the pod, there's the comments that brain_d_foy mentioned (WTF Was I Thinking).
By my quick count, it's almost 1300 lines total (blanks included), with about 400 lines being pod, 200 non-pod related blank lines, and 350 lines of comments. (leaving about 400 lines actually containing something useful ... although half of those are just for legibility)
Update: blah...fixed typo in first line (does or _doesn't_)
|