Google Testing Blog

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()) { ... }