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."

8 of 500 comments (clear)

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

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

  2. 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
  3. 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
  4. I was skeptical at first regarding the topic by Anonymous Coward · · Score: 5, Insightful

    But when reading the article I was glad that the very first item was SELF DESCRIBING CODE. The most important part of code documentation is the code iteself IMHO.

    I think it was Fowler who once went as far as to state that when you find yourself needing to document code in order for it to be understood (vs. thoroughness, completness, or document generation) you probably need to refactor your code.

    How many times have we come across code like this?

    public void bigFunction1()...

    public void bigFunction2()...

  5. 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
  6. A comment on comments by Jeffrey+Baker · · Score: 5, Insightful
    Dear Doxygen and JavaDoc users,

    The following is an example of useless documentation:

    frobWoggleFfloofMoing

    public void frobWoggleFfloofMoing(String, String, String)

    Frobs the Woggle

    ...

    You see, running Doxygen over your header files may produce some output in HTML format, but it doesn't produce what I like to call "documentation." For instance, documentation would explain what is a Woggle, and when should it be Frobbed?

    Thank you, and have a nice life.

  7. zerg by Lord+Omlette · · Score: 5, Insightful

    Ask someone else to look at your code. Every time they pause while scrolling, touch their chin, squint their eyes, furrow their brows, etc., it means you need a comment.

    --
    [o]_O
  8. Re:What makes a good Comment? by mOdQuArK! · · Score: 5, Insightful
    You really should comment every line of assembly, even when you just increment a register,

    As long as you're commenting the _real_ effect of the instruction, and not just mindlessly repeating what the mnemonic already tells the reader. I've seen lots of stupid assembly-language comments like "increments the A register". Gee, thanks - I couldn't have figured that out from the "INC A" mnemonic.