Stories
Slash Boxes
Comments
NOTE: use Perl; is on undef hiatus. You can read content, but you can't post it. More info will be forthcoming forthcomingly.

All the Perl that's Practical to Extract and Report

The Fine Print: The following comments are owned by whoever posted them. We are not responsible for them in any way.
 Full
 Abbreviated
 Hidden
More | Login | Reply
Loading... please wait.
  • by pudge (1) on 2001.12.05 9:49 (#2119) Homepage Journal
    ... but I basically agree. I only write long comments (that is, sentences instead of short phrases) when it is to discuss why the code is doing what it is doing, rather than discussing what it is doing; or, if what it is doing is really really weird, and I want to explain it to myself (or someone else) later on. The latter case is quite rare, and I cannot recall an example of it offhand. The former case happens once or twice a month, maybe.

    Most of my comments are just quick labels saying what something is for quick reference. And I think it works well. If someone doesn't understand an idiom I use, I ask them to come to me and I will explain it, quite happily. I won't explain it in the code. It just bloats it, and doesn't really help anyone.

    And while you state it, perhaps you don't emphasize the point enough: code needs to be well-written. Common idioms, consistent style, reasonable whitespace and parentheses ... all these things are extremely important, and contribute well to quickly scanning code. The brain is good with things like that.
    • Oh yeah? I've blown sweeter notes out of my ass-aphone!

      I'm in agreement with your clarifications, Pudge-daddy. Once again, you have crystalized my thoughts eloquently.