Good comments, Bad comments

/**
/* Vietnamese:
/* Đôi điều suy nghĩ về cách thức ghi chú (comment) trong mã nguồn.
/* Nếu bạn là một lập trình viên từng bực mình đến phát điên vì ai đó code “chuối”,
/* có lẽ bạn sẽ quan tâm đến những điều tôi viết dưới đây
**/

Not too long ago, I came across an “interesting” question on StackOverflow. It was “What is the best comment you have ever seen?“.

The answer list is very very long with thousands of comments. The highest-voted answer is a comment “placed far, far down a poorly-designed God Object“:

/**
* For the brave souls who get this far: You are the chosen ones,
* the valiant knights of programming who toil away, without rest,
* fixing our most awful code. To you, true saviors, kings of men,
* I say this: never gonna give you up, never gonna let you down,
* never gonna run around and desert you... /*a lot more here*/
*/

Well, it seems all of us developers need a little humor to spice up our steady (sometimes tedious) work. In a work environment with lots of tension, laughs are always loved.

But the thing that caught my eyes in that SO question is not humor. I mean dirty code, which smell through the comments.

// somedev1 - 6/7/02 Adding temporary tracking of Login screen
// somedev2 - 5/22/07 Temporary my ass

From that comment, you see how long a hotfix can live.

#define TRUE FALSE //Happy debugging suckers

If you quit your job, at least don’t treat the maintainers like that.

//Dear future me. Please forgive me.
//I can't even begin to express how sorry I am.

You may think it’s funny. Actually, to me it’s not. Please remember that 60% of developing effort is put on, not coding, but debugging.

Bad code along with poor comments is truly a nightmare to developers. Do you want days in & days out fix bugs caused by comments like this, please go on:

/** * Always returns true. */
public boolean isAvailable()
{
return false;
}

So the question is that: how good a comment should be?

Accoring to Robert C. Martin, comments don’t make up for bad codes. In stead, code should speak for itself, by good naming & structure. For a very simple example, the following code doesn’t have a comment, but it should be fine by itself:

      User currentUser = userService.getCurrentUser();
      if (currentUser != null) {
            if (urlOnlyAllowAnonymousAccess(requestUrl)) {
                log.info("An authenticated user try to access a non-logged-in link. Redirect to homepage");
                httpServletResponse.sendRedirect(contextPath + "/account/home.do");
                return;
            }

            if (urlNotAllowNonActivatedTVAccess(requestUrl)) {
                TVTracking tvTracking = currentUser.getAssociatedTV();

                if (tvTracking == null) {
                    log.info("A non-activated user is trying to access settings. Redirecting to activation page");
                    httpServletResponse.sendRedirect(contextPath + "/account/activate.do");
                    return;
                }
            }
        }

One thought on “Good comments, Bad comments

  1. Pingback: Blog Review: Should I comment code? | Lexical Scope

Comments are closed.