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. var names by rockytriton · · Score: 3, Insightful

    My best strategy is intelligent variable names and clean simple code. -- http://www.dreamsyssoft.com

  2. 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()...

  3. Commenting by Hamster+Of+Death · · Score: 4, Insightful

    Write the comments first, then add the code. That way you'll get a better grasp on the problem you're solving. If your comments don't explain the problem or someone else can't solve the problem using your comments then you'll probably need to rethink your approach.
    And for crying out loud update the comments when you change code!
    *grumbles about 10 year old code and 15 year old comments*

    1. Re:Commenting by bmwm3nut · · Score: 3, Insightful

      exactly! in fact, this was taught to me by a senior programmer who said: "you should never document your code, your should code your document." in projects where i've followed that rule, i've had many fewer problems than ones where i jumped into the code quickly.

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

  5. How & Whys by Anonymous Coward · · Score: 4, Insightful

    It's been said before, but I find the best advice I've ever gotten on commenting code is very simple -

    Comment the why, not the how.

    Hopefully the code should be clear enough to pick out the how, but *why* you are doing something is never going to be apparent from the code itself - at best someone might be able to infer it, but that becomes especially tricky when time passes or a new person signs on.

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