Slashdot Mirror

← Back to Stories (view on slashdot.org)

Successful Strategies for Commenting Your Code

Posted by Hemos on from the good-things-to-learn dept.

LilG writes "Over at Particletree, Ryan Campbell writes about Successful Strategies for Commenting Your Code. His essay gives advice and examples on proper commenting, and details some different strategies."

10 of 500 comments (clear)

  1. Huh? by tntguy · · Score: 5, Funny

    These comments you speak of, they seem foreign and strange to me.

    1. Re:Huh? by MHobbit · · Score: 4, Funny

      A TRUE Klingon warrior does not comment his code!

      *ducks*

      --
      Debugging? Klingons do not debug. Bugs are good for building character in the user.
  2. My favorite code comment not written by me by dcarey · · Score: 4, Funny

    I was doing some maintenance on someone else's code and came across this nasty set of like 8 nested if/elses. It was a bloody horrible hack. But the best part of all was the comment right at the top: /* Oh, fuck */

    --

    -- (Score:i , Imaginary)

    1. Re:My favorite code comment not written by me by lukewarmfusion · · Score: 4, Funny

      So you found that, eh? *evil chuckle*

      I was in a similar spot a month or two ago and found some other company's comments - unhelpful as always - in the form of typed out sound effects.

      # This function goes vroooooooommm-pop!

      I have no idea why the developers put such comments there other than to entertain themselves as they sifted through their horribly written Perl.

  3. Practice what you preach by ChrisF79 · · Score: 5, Funny

    I viewed the source on the site and nothing was commented :)

    --
    Finance tutorials and more! Understandfinance
  4. Comments are more important than Code? by jetkust · · Score: 4, Funny

    Comments are more important than Code?

    I once tried writing code that was completely made up of comments. It was easy to write and all, but didn't work very well.

    1. Re:Comments are more important than Code? by NialScorva · · Score: 4, Funny

      At least you had no compile errors or core dumps, and I bet you didn't have any exploitable vulnerabilities either.

  5. Don't comment by i.r.id10t · · Score: 5, Funny

    Don't comment at all, and just run it thru The Commentator!

    http://www.cenqua.com/commentator/

    --
    Don't blame me, I voted for Kodos
  6. No by rbarreira · · Score: 5, Funny

    No, that first one should be something like:

    This loop starts at 1, and to 5 it counts. It doesn't count to 6, nor it does count to 8. It does not count to 3 or 4, except in passage to 5. When it reaches number 5, the fifth number...

    --

    The AACS key is NOT 0xF606EEFD628B1CA427BEA93A9CA9773F
  7. Things to always remember when commenting by WillAffleckUW · · Score: 4, Funny

    1. Never spelchezk.
    2. Use randomly chosen variable names, or objects that resemble your favorite Orcs and Trolls from LotR - after all, everyone knows that a Lothlorien object will have farseeing ability, so it's obvious.
    3. When instantiating something for the first time, never explain it - real programmers read the original object source.
    4. If you do something complex, write a short pithy comment like /* magic occurs */
    5. If you do something easy but you were drinking too much hot cocoa, write a long verbose description, and also mention how good the hot cocoa was.
    6. Always include song lyrics to what you're listening to while you wrote the code.
    7. Object inheritence means never having to explain the code.
    8. Repetition is the best way to reinforce obvious things - so repeat the obvious thing since it's the best way to reinforce it.
    9. If you break up with your girl/boyfriend, write about it in the comments - people really want to know.
    10. If you're updating or modifying code, write your opinion about the original code in the comments. Use nasty words if you can.

    --
    -- Tigger warning: This post may contain tiggers! --