« /** no comment */ | Main | Another Sun Dev Day Review »

Commenting example

In response to Chris Justus again, here's how I'd comment his example.

The example he had was:


// Stripping trailing phone extensions for contact numbers for other group X, system XYZ... 
String newNum = "";
keepGoing = true;
for(int c=0;c
  char ch = oldNumber.charAt(c);
  if (ch >= '0' && ch <='9' && keepGoing) {
     newNum += ch;
   } else if (ch  '(' || ch  ' ' || ch  'x' || ch  'X')) {
     keepGoing = false;
   }
}

And here's how I would do it:


  String newNum = stripPhoneExtension(oldNumber);

// later in the class...

/**
 * Strip the extension from a phone number. Everything before the extension
 * will be returned.
 * @return the (stripped) phone number.
 */
private String stripPhoneExtension(String phoneNumber) {
   int phoneNumberLength = phoneNumber.length();
   char[] extensionMarkers = {'(', ' ', 'x', 'X'};
   
   for (int index = 0; index < phoneNumberLength; index++) {
      char phoneDigit = phoneNumber.charAt();
      if (isCharInArray(phoneDigit, extensionMarkers)) {
         return phoneNumber.substring(0, index);
       }
    }
   return phoneNumber;
}

/**
 * Check to see if a char is in an array. Similar to the
 * List.contains() method, but useful where performance may be
 * an issue.
 * @param searchTerm the char to look for.
 * @param charArray the array to look in.
 * @return true if the char is present in the array, otherwise false.
 */
private boolean isCharInArray(char searchTerm, char[] charArray) {
   for (int i = 0; i < charArray.length; i++) {
      if (searchTerm == charArray[i]) {
         return true;
       }
    }
   return false;
}

Actually, for private methods like these, the param and return tags are probably overkill, but for public or protected methods I would put them there.

Hopefully that clears up some misunderstandings.

Post a comment


About

This page contains a single entry from the blog posted on June 10, 2004 2:18 PM.

The previous post in this blog was /** no comment */.

The next post in this blog is Another Sun Dev Day Review.

Many more can be found on the main index page or by looking through the archives.

Creative Commons License
This weblog is licensed under a Creative Commons License.
Powered by
Movable Type 3.35