Slashdot Mirror

← Back to Stories (view on slashdot.org)

What is Well-Commented Code?

Posted by Cliff on from the inlined-internal-documentation dept.

WannaBeGeekGirl queries: "What exactly is well-commented code anyway? Can anyone suggest resources with insight into writing better comments and making code more readable? After about six years in the software development industry I've seen my share of other people's code. I seem to spend a lot of time wishing the code had better (sometimes _any_) comments. The comments can be frustrating to me for different reasons: too vague, too specific, incoherent, pointing out the obvious while leaving the non-obvious to my imagination, or just plain incorrect. Poorly or mysteriously named variables and methods can be just as confusing. In a perfect world everyone would follow some sort of coding standards, and hopefully those standards would enforce useful comments. Until then, any suggestions for what you, as a programmer, consider to be good/useful/practical comments? Any suggestions for what to avoid? Also, I usually work with C++ so any resources/comments specific to that language would be too."

5 of 802 comments (clear)

  1. first post by Anonymous Coward · · Score: -1, Offtopic

    I can't believe I'm actually doing this. :-)

    1. Re:first post by Anonymous Coward · · Score: -1, Offtopic

      Well, you did and you're an Anonymous Turd sucker, so FUCK YOU!

  2. reply by fixed · · Score: -1, Offtopic

    it looks like I ::MAY:: have gotten the first post... doubt it though

  3. Suck my dick by Anonymous Coward · · Score: -1, Offtopic

    And the truth shall be revealed. That is how you become a REAL Geek Girl.

  4. No, Call it what it is by Anonymous Coward · · Score: -1, Offtopic

    Knob bobbin'. No Geek Girl wannabe is worth a fart if she can't get it right.