Do You Comment Too Much?

Commenting is obviously an important part of programming, but it is possible to take it too far. Too many comments can muddle the readability of code.

Overcommented Code

When I was a TA at Carnegie Mellon University, we always made code commenting worth 10 out of 100 points on a project. Students understood when they received no points for not commenting, but they would always complain when they were docked points for commenting too much. However, developers can take it to extremes when we do things like this:

/**
 * Counts the number of times char c shows up in String str
 */
public int countChar(char c, String str) {
  // intialize the count
  int count = 0;

  // loops until end of string
  for (int i=0; i<str.length; i++) {
    // if character in string at position i is equal to c
    if (str.charAt(i) == c) {
      // increase count
      count++;
    }
  }

  // returns the count
  return count;
}

I find this to be harder to read than if the code had no comments at all:

/**
 * Counts the number of times char c shows up in String str
 */
public int countChar(char c, String str) {
  int count = 0;

  for (int i=0; i<str.length; i++) {
    if (str.charAt(i) == c) {
      count++;
    }
  }

  return count;
}

I am in no way saying that code should not be commented. Instead, it should only be commented in situations where the comments are there for a reason, instead of being a copy of the line of code below it.

How to Know When to Comment

Situations that deserve comments:

• Complicated nested loop structure - This is the textbook case and should be clear.
• Assumptions - If you are coding or omitting a case because of an assumption or a "guaranteed" situation found earlier in the code (even in the same function), comment that you are making this assumption
• Strange Requirements - Sometimes you have to code something in a strange way due to strange requirements. In this case, cite the requirement (document name, section, and page) in the comments so another coder coming back to this section won't think it looks weird and try to "fix" working code
• A hack, fix, or exception for a specific bug or request - cite the bug number or the requester's name and date requested
• TODOs/FIXMEs - There are many situations where a portion of code is left unfinished or hacked due to time constraints. It may be a case that you do not have to deal with yet but might in the future, or it may be a quick bug fix. In these cases leave a comment with a TODO or FIXME flag so it will be more likely someone will get back to it, and so another person working in the code looking for a bug may realize that it was something not implemented in the first place.

Commenting code is important, but it's also important that it's only used in certain situations. For example, writing javadocs for getters and setters on POJOs are unnecessary. If the API user cannot figure out what getName() and setName(String name) do, then I'm not really sure a comment would help them. Use comments for a purpose.