This is another post in our Code Health series. A version of this post originally appeared in Google bathrooms worldwide as a Google Testing on the Toilet episode. You can download a printer-friendly version to display in your office.





By Dori Reuveni and Kevin Bourrillion





While reading code, often there is nothing more helpful than a well-placed comment. However, comments are not always good. Sometimes the need for a comment can be a sign that the code should be refactored.





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;

// Filter offensive words. for (String word : words) { ... } filterOffensiveWords(words); Extract a method.

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: