Mike’s Dump

June 25, 2007

RE: Is there an issue with this or am I not getting enough oxygen?

Filed under: Code — mikesdump @ 2:01 pm

In my previous post I showed an example of what not to do when writing comments. To my amazement this non-rant generated almost as many comments as this post.

After reading the comments and giving it some more thought I wanted to post a follow-up. I don’t believe these type comments are unique to a tool like VBCommenter, one development shop or one programming language. I believe this is a very common issue when documenting source code.

I had another post a couple years ago about documentation and my views haven’t really changed. I still believe the most important piece of documentation for a project is the requirements.

If you insist in commenting the code (which I’m not arguing against) I suggest the following rules:

Document WHY not WHAT
Even really crappy code can be debugged. Call me sick but I kind of like debugging crappy code from time-to-time because it is extra satisfying when I fix it. When you are cursing the previous developer’s name are you screaming at them, “WHAT are you doing”? or “WHY did you do that”? I find it a lot easier to figure out the what but the why can be a little trickier.

Remember you who are writing for

The primary person the in code documentation is for is the developer(s) that inherit your code not for you. I believe a class header outlining the purpose of the class is far more valuable than commenting every method. If you had to explain the application to a developer that was going to take over for you what would you tell them? Would you say, “here is the page_load event, it will load the page”? Probably not, you are hopefully going to tell them some of the challenges you ran into and why the application is the way it is.

Never Copy and Paste Comment Block headers

Please, if you must copy comment headers remember to update them. I don’t know how many times over the years I have read the comments of method A right above method B because the developer copied the comments and didn’t update them.

Read them and keep them current

If you are maintaining some code and the person before you took the time to write good comments make sure they are still current after your change. If you aren’t going to bother updating them it is better to delete them than leave comments that don’t match the code.

Commenting code can add value to a project but it is a team effort. I don’t believe there is any magic to writing good comments but it does take time and you do have to put some thought into it. If you hate writing comments that much you could always try this.

Advertisements

9 Comments »

  1. Oh man! That is a wicked black leather look you were sporting. No wonder you got so many comments 😛 Mike, the unofficial fifth member of the Ramones

    I very much agree with "Document WHY not WHAT". I don’t need comments telling me that "now we increment i by 1", that’s what "i++" is for.

    It’s quirky, though. I’ve found if you’re commenting with that mentality, excessive comments become almost a code smell. Like "this code should be straightforward, yet why am I having to explain and justify the heck out of all this code." Sometimes it makes me refactor, othertimes it’s becomes "oh well, I guess this bit was just hard."

    Comment by jamesk — June 27, 2007 @ 12:51 pm | Reply

  2. That was a great coat!

    I hear you on the code smell. I still do inline comments but I really like the idea of anytime you feel the need to add inline comments refactor by either introducing a variable or creating a new method.

    Come to think of it I have some Java Script in my current project I should refator for this very reason.

    Comment by mike — June 27, 2007 @ 4:06 pm | Reply

  3. I agree to not blame the tool, blame the developer.

    But what is wrong with little or no commenting?

    Personally, code coupled with BDD, and good REFACTORING would make you avoid comments… "Read your code like a book"

    Also, treating method’s with SRP would definately make it more readable and easy to understand…

    For example:


    view.Radius = CalculateRadiusFrom(itemToCalculate.Text);

    public decimal CalculateRadiusFrom(int item)
    {
    return item * GetRadius();
    }

    Comment by Jonas Avellana — June 28, 2007 @ 6:09 am | Reply

  4. oh yea… i forgot Convert.ToInt32(…)

    Comment by Jonas Avellana — June 28, 2007 @ 6:10 am | Reply

  5. Jonas the code writer…

    I had to expand on your example but I think the following would be a good example of when we really need comments.

    I personally think for smaller methods reading like a book is fine but for larger methods (no not god methods! Just methods which cannot be refactored for some unknown reason) comments are necessary.

    I think to make code read like a book you need to make sure methods are small and light. The example below is small but you have to imagine…

    Most developers won’t have a problem reading/comprehending from one style to the next.


    view.Diameter = CalculateDiameter(view.Radius);

    // <summary>
    // This method is used to calculate the diameter.
    // </summary>
    // <remarks>
    // If the radius entered is a negative number the function will return a 0 to prevent a negative diameter which would cause premature detonation.
    // </remarks>
    public decimal CalculateDiameter(int radius)
    {
    //Guard statement to check if the radius is negative which would our calculations out of wack.
    if (abs(radius) != radius)
    {
    return 0;
    }
    else
    {
    return radius * 2;
    }
    }

    Comment by James Wong — June 28, 2007 @ 9:21 pm | Reply

  6. Haha smells like a codesmell james!

    I’m not super against commenting, I’m just saying that there are various techniques to have a readable class without comments.

    I just hate how comments are the "last" thing you always have to do, and some(most)times never updated..

    Here’s my take on james’ take


    view.Diameter = CalculateDiameterFor(view.Radius);

    public decimal CalculateDiameterFor(int radius)
    {
    if (IsAbsoluteValueOf(radius))
    return radius * 2;
    }

    private static decimal IsAbsoluteValueOf(int radius)
    {
    return Math.Abs(radius) != radius;
    }

    Comment by Jonas Avellaa — July 2, 2007 @ 3:26 pm | Reply

  7. RE – "I personally think for smaller methods reading like a book is fine but for larger methods"

    Large methods are already a codesmell itself and definately requires refactoring…

    Wow I love how Overlord’s blog is now like a forum for people that care about development!

    We just need some topless pics of overlord!~

    Comment by Jonas Avellaa — July 2, 2007 @ 3:30 pm | Reply

  8. My 2 cents on James’s method

    The summary comment on your method I can get out of the method name, kinda redundant in my opinion. I like the “remark” comment (I’d put it in the “return” node) which makes it clear what would be returned.

    //Guard statement to check if the radius is negative which would our calculations out of wack.
    if (abs(radius) != radius)

    What I loved about the above comment is I understand what you were trying to do. That way I would feel comfortable refactoring to (wasn’t sure if 0 was allowed or not based on the comment).

    //Guard statement to check if the radius is negative which would our calculations out of wack.
    If (radius >=0)
    {
    return radius *2;
    }
    else
    {
    return 0;
    }

    Comment by mike — July 2, 2007 @ 6:19 pm | Reply

  9. I don’t have any topless pictures only bottomless, are those ok?

    My 2 cents on Jonas’s methods:

    Unless I’m forgetting something I don’t think your CalculateDiameterFor method would compile 🙂
    You need to return on the ELSE as well.

    I agree that the IsAbsoluteValueOf method makes it a little more readable WHAT the code is doing but using the ABS method like James did I think is ok too. The first point I made in this post was document "WHY NOT WHAT" and I think that is what was lost between your two solutions.

    I’m guessing your comeback would be that would be covered in the unit test but personally, I still find it useful to see those types of comments.

    Comment by mike — July 2, 2007 @ 6:20 pm | Reply


RSS feed for comments on this post. TrackBack URI

Leave a Reply

Fill in your details below or click an icon to log in:

WordPress.com Logo

You are commenting using your WordPress.com account. Log Out / Change )

Twitter picture

You are commenting using your Twitter account. Log Out / Change )

Facebook photo

You are commenting using your Facebook account. Log Out / Change )

Google+ photo

You are commenting using your Google+ account. Log Out / Change )

Connecting to %s

Blog at WordPress.com.

%d bloggers like this: