Code & Bug FixesSoftware and Apps

Code: To Comment or Not to Comment?

While reading code, often there is nothing more helpful than a well-placed comment. However, comments are not always good.

Use a comment when it is infeasible to make your code self-explanatory. If you think you need a comment to explain what a piece of code does, first try one of the following:

  • Introduce an explaining variable.
    // Subtract discount from price. finalPrice = (numItems * itemPrice) – min(5, numItems) * itemPrice * 0.1; price = numItems * itemPrice; discount = min(5, numItems) * itemPrice * 0.1; finalPrice = price – discount;
  • Extract a method.
    // Filter offensive words. for (String word : words) { … } filterOffensiveWords(words);
  • Use a more descriptive identifier name.
    int width = …; // Width in pixels. int widthInPixels = …;
  • Add a check in case your code has assumptions.
    // Safe since height is always > 0. return width / height; checkArgument(height > 0); return width / height;

There are cases where a comment can be helpful:

  • Reveal your intent: explain why the code does something (as opposed to what it does).
    // Compute once because it’s expensive.
  • Protect a well-meaning future editor from mistakenly “fixing” your code.
    // Create a new Foo instance because Foo is not thread-safe.
  • Clarification: a question that came up during code review or that readers of the code might have.
    // Note that order matters because…
  • Explain your rationale for what looks like a bad software engineering practice.
    @SuppressWarnings(“unchecked”) // The cast is safe because…

On the other hand, avoid comments that just repeat what the code does. These are just noise:

// Get all users. userService.getAllUsers(); // Check if the name is empty. if (name.isEmpty()) { … }
Google Testing Blog

Related Articles

Leave a Reply

Your email address will not be published. Required fields are marked *