Comments

Symptoms

• Comment symbols ( // or /* ) appear in the code. (Some IDEs help by color coding different types of comments.)

Causes

Comments may be present for the best of reasons: The author realizes that something isn't as clear as it could be and adds a comment.

Some comments are particularly helpful:

• Those that tell why something is done a particular way (or why it wasn't)

• Those that cite algorithms that are not obvious (where a simpler algorithm won't do)

Other comments can be reflected just as well in the code itself. For example, the goal of a routine can often be communicated as well through the routine's name as it can through a comment.

What to Do

• When a comment explains a block of code, you can often use Extract Method to pull the block out into a separate method. The comment will often suggest a name for the new method.

• When a comment explains what a method does (better than the method's name!), use Rename Method using the comment as the basis of the new name.

• When a comment explains preconditions, consider using Introduce Assertion to replace the comment with code.

Payoff

Improves communication. May expose duplication.

Contraindications

Don't delete comments that are pulling their own weight.

EXERCISE 3 Comments.

Consider this code. (Online at www.xp123.com/rwb )

Matcher.java

 public class Matcher {     public Matcher() {}     public boolean match(int[] expected, int[] actual,         int clipLimit, int delta)     {         // Clip "too-large" values         for (int i = 0; i < actual.length; i++)             if (actual[i] > clipLimit)                 actual[i] = clipLimit;         // Check for length differences         if (actual.length != expected.length)             return false;         // Check that each entry within expected +/- delta         for (int i = 0; i < actual.length; i++)             if (Math.abs(expected[i] - actual[i]) > delta)                 return false;         return true;     } } 

MatcherTest.java

 import junit.framework.TestCase; public class MatcherTest extends TestCase {     public MatcherTest(String name) {super(name);}     public void testMatch() {         Matcher matcher = new Matcher();         int[] expected = new int[] {10, 50, 30, 98};         int clipLimit = 100;         int delta = 5;         int[] actual = new int[] {12, 55, 25, 110};         assertTrue(matcher.match(expected, actual, clipLimit, delta));         actual = new int[] {10, 60, 30, 98};         assertTrue(!matcher.match(expected, actual, clipLimit, delta));           actual = new int[] {10, 50, 30};           assertTrue(!matcher.match(expected, actual, clipLimit, delta));           } } 

1. Use Extract Method to make the comments in match() redundant.

2. Can everything important about the code be communicated using the code alone? Or do comments have a place?

3. Find some code you wrote recently. Odds are good that you commented it. Can you eliminate the need for some of those comments by making the code reflect your intentions more directly?

See Appendix A for solutions.