Javadoc comments - CompareTo?

Question

My book asks me to write a Javadoc comment for a section of code. For the most part I understand how to do javadocs, but I do not understand what the program is doing.

"Write a Javadoc comment for the following method of a class Person. Assume that class Person has two String data fields lastName and firstName with the obvious meaning. Provide preconditions and postconditions if needed."

public int compareTo(Person per) {
    if (lastName.equals(per.lastName))
        return firstName.compareTo(per.firstName);
    else
        return lastName.compareTo(per.lastName);
}

/**
 * Method to return?
 *
 * @param compare the firstName lexicographically
 * @param compare the lastName  lexicographically
*/

I actually have no idea what this is doing. Is it returning a number? I looked at examples on

http://www.tutorialspoint.com/java/java_string_compareto.htm

`I actually have no idea what this is doing`...well I can tell that compiling is one thing it is _not_ doing. There is no `Public` keyword in Java. Just Google Javadoc and look at a tutorial. — Tim Biegeleisen, Aug 11 '15 at 04:29
That is what the question asks, really odd. It does say public not Public. — beginningprogrammer, Aug 11 '15 at 04:44
It looks like you are missing an `if` statement. Without that, I can't tell what it's doing either. Having said that, this `compareTo` is using a different `compareTo` that is defined for `String` objects, and you can find out what it means by looking at the documentation [here](http://docs.oracle.com/javase/8/docs/api/java/lang/String.html). — ajb, Aug 11 '15 at 04:48
You're right, I missed the if statement. It is suppose to read if (lastName.equals(per.lastName) — beginningprogrammer, Aug 11 '15 at 04:54
I don't know why everyone's getting bent out of shape about your code not compiling. Yes, you should [post correct code](http://stackoverflow.com/help/how-to-ask) when asking for help, but your question is pretty clear to me. — dimo414, Aug 11 '15 at 05:05
I don't blame them I should have posted it correctly the first time. — beginningprogrammer, Aug 11 '15 at 05:22

score 2 · Accepted Answer · answered Aug 11 '15 at 04:49

2

Are you sure it doesn't look like this?

Public int compareTo(Person per) {
    if(firstName.compareTo(per.firstName) != 0){
        return firstName.compareTo(per.firstName);
    }
    else{
        return lastName.compareTo(per.lastName);
    }

}

This code will order based off the lexicographically ordering of the first name, if they are the same it will then sort off the last name.

Each compareTo method returns a -1, 0, or 1 depending on if the first string comes sooner in the ordering or not.

answered Aug 11 '15 at 04:49

Pumphouse

2,013
17
26

Yeah you're right, I forgot to add the if statement. Thanks this is starting to make sense. So what is this doing exactly? Comparing the set firstName to the Per.firstName and seeing if they are the same? If they are it returns -1? I'm still a little lost – beginningprogrammer Aug 11 '15 at 05:01
@beginningprogrammer it's checking the first name. If they are the same it then checks the second name. For Example say the names are Andy and Barb. Andy.compareTo("Barb") returns -1, since a comes before B. Barb.comparTo("Andy") returns 1 since B is greater than A lexigraphically. If they are the same Andy.compareTo("Andy") will return 0. – Pumphouse Aug 11 '15 at 05:05
@beginningprogrammer if they are the same, then they may have the same first name, so it goes to the last name and does the same thing. If that returns 0 it's the same first and last name. – Pumphouse Aug 11 '15 at 05:06
@beginningprogrammer the compareTo method is used by other data structures to order entries. For example if you put this in a list and called sort, it would use the compareTo method to sort the list. – Pumphouse Aug 11 '15 at 05:07

Amit Bhati · Answer 2 · 2015-08-11T05:00:34.790

First your compareTo method doesn't look appropriate to me :- Public should be public.

Secondly your method is comparing two Person objects based on the firstName or lastName lexicographically i.e. alphabetical order (A comes before B or A<B) and returning an integer value.

For example:-

     String firstName1="B";
     String firstName2="A";
     String firstName3="B";
     String firstName4="C";

     System.out.println(firstName1.compareTo(firstName2));
     System.out.println(firstName1.compareTo(firstName3));
     System.out.println(firstName1.compareTo(firstName4));

Output: 1
 0
-1

If firstName1 < firstName3 then -1 (negative integer, first is smaller than second)
If firstName1 > firstName2 then 1 (positive integer, first is bigger than second)
If firstName1 == firstName2 then 0 (zero, both are equal)

Now coming to your compareTo method, it should be like this:-

     public int compareTo(Person per) {
            int i= firstName.compareTo(per.firstName);
            if(0!= i) return i;
            else
            return lastName.compareTo(per.lastName);
        }

score 1 · Answer 3 · answered Aug 11 '15 at 04:55

"Lexographically" means it would appear after the other String or before other String if sorted by the unicode value of its (left-justified or right-justified) characters.

Add this, to your code and show us the result -

System.out.println(Arrays.toString((per.firstName).getBytes())); 
System.out.println(Arrays.toString((firstName).getBytes()));

System.out.println(Arrays.toString((per.lastName).getBytes()));
System.out.println(Arrays.toString((lastName).getBytes()));

score 1 · Answer 4 · answered Aug 11 '15 at 05:00

Let's get it out of the way now: this is syntactically invalid code. Valid code would look like this:

public int compareTo(Person per) {
    if(firstName.compareTo(per.firstName) != 0) {
        return firstName.compareTo(per.firstName);
    } else {
        return lastName.compareTo(per.lastName);
    }
}

Now, to the Javadoc you've got.

@param indicates the valid parameters to the function. You only have one, so you may only have one @param declaration.
Since this method returns a value, you need to have a @return declaration.

This would change your Javadoc to this.

/**
* Method to return?
*
* @param per the person
* @return a value < 0, 0, or > 0 if...
*/
public int compareTo(Person per) {
    if(firstName.compareTo(per.firstName) != 0) {
        return firstName.compareTo(per.firstName);
    } else {
        return lastName.compareTo(per.lastName);
    }
}

The section after /** is where you place implementation specific information; stuff that's useful for someone using this method to know. Considering that this method doesn't check to see if any first or last name is null or not, that would be valuable to include here. The rest I leave as an exercise for the reader.

score 1 · Answer 5 · answered Aug 11 '15 at 05:03

Your book should have explained at some point what a Comparable is. Comparisons in Java are done by returning an integer (meaning less-than, greater-than, or equal-to the passed in value) from the compareTo() method. The method you posted is comparing a Person on the basis of their first and last names. If their last names are equal, their first names are used for comparison. Otherwise, their last names are used.

This would order a group of People like so:

Doe, John
Obama, Barack
Smith, John
Smith, Sally

Javadoc comments - CompareTo?

5 Answers5