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 = '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.