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

use Perl Log In

Log In

[ Create a new account ]

Beatnik (493)

Beatnik
  (email not shown publicly)
http://www.ldl48.org/

A 29 year old belgian who likes Mountain Dew, Girl Scout Cookies, Tim Hortons French Vanilla Flavoured Cappucinno, Belgian beer, Belgian chocolate, Belgian women, Magners Cider, chocolate chipped cookies and Perl. Likes snowboarding, snorkling, sailing and silence. Bach can really cheer him up! He still misses his dog.

Project Daddy of Spine [sf.net], a mod_perl based CMS.

In his superhero time (8.30 AM to 5.30 PM), he works on world peace.

Journal of Beatnik (493)

Thursday July 14, 2005
09:55 AM

Good thing or bad thing

[ #25706 ]
Just now I realized some of my more recent code has more comments than actual code.. Is that a good thing or a bad thing? I am growing old and is it time to shoot me while I still haven't looked into .NET yet??
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.
  • When I'm reading other peoples code I generally like comments that explain non-obvious algorithms, or places where the author hit a snag or bug and is alerting future maintainers.

    I generally don't like comments that explain obvious or trivial code.

    I like to revisit my code after a couple of months and see if the comments still make sense. Lots of times I end up stripping them out or re-writing them.

    -- Douglas Hunter
  • Bad, if you ask me.

    Structuring code well, choosing identifiers carefully, and using whitespace generously makes code mostly self-explanatory. The reason why the code is there and how to use it should be documentation. Comments are for explaining non-obvious algorithms, for calling attention to lurking bugs, or other problems, and the like.

    Basically, the documentation should explain why the code is there, and the code should explain how it works. Comments are only for highlighting surprising points in th

    • There are large chunks refering to other documentation, changelogs and technical requirements. There are also the sections not explaining how the code works but why it is done like it is..
      • "There are also the sections not explaining how the code works but why it is done like it is.. "

        The key to good comments is to explain why, not how. Kudos. As previously mentioned, good code makes the "how" clear.