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.

Author: Robert Watkins

My name is Robert Watkins. I am a software developer and have been for over 20 years now. I currently work for people, but my opinions here are in no way endorsed by them (which is cool; their opinions aren’t endorsed by me either). My main professional interests are in Java development, using Agile methods, with a historical focus on building web based applications. I’m also a Mac-fan and love my iPhone, which I’m currently learning how to code for. I live and work in Brisbane, Australia, but I grew up in the Northern Territory, and still find Brisbane too cold (after 22 years here). I’m married, with two children and one cat. My politics are socialist in tendency, my religious affiliation is atheist (aka “none of the above”), my attitude is condescending and my moral standing is lying down. View all posts by Robert Watkins