Incremental Java
Method Signatures

Method Names

Last time, we talked about objects responding to commands or operations. In Java, we call these method. Method names are identifiers, so they follow the rules for identifiers. They also follow the same style rules as variable names.

Method names tell an object what to do. A class designer decides what base operations an object should respond to, and gives each operation a name. More complex operations are sometimes done by doing several base operations in sequence.

There were the list of Rectangle method names we came up with in the last lesson:

Parameters

Think about the method setHeight. An object reacts to methods. One way to react is by the name of the method. Thus, an object does one thing if the method is getArea, but something else if it is setHeight.

Clearly, Java wants different method names to (potentially) do different things to the object.

Is the method name enough? In particular, is the setHeight method name enough information to change the height of the Rectangle object? The answer is clearly no. You must pick what height you want the Rectangle method to be.

You can't tell a Rectangle object that you want to set its height (using setHeight). You must provide two pieces of information. Obviously, you need the method name. In this case, setHeight. Youu also need to provide the height too.

In Java, as in many OO languages, methods can include parameters. Parameters are additional pieces of information given to the object along with the method name.

Syntax for Parameter Lists

What does it mean to provide information? We have to provide a height to setHeight. What is height? It's a value. In Java, values have types, so perhaps we should think of parameters as variables with types. This is essentially what a parameter list is.

Here's an example: 

   setHeight( int newHeight ) ;
A parameter list begins with an open parenthesis, followed by zero or more parameters, separated by commas (if there are at least two parameters). A parameter is a type followed by at least one whitespace, followed by a parameter name. All parameter names in a parameter list must be unique.

In this case, we have a single parameter in the parameter list.

Imagine we had a method called setRect which sets the height and width. This requires two values. Each value requires a parameter, so we'll need two parameters.

The method and parameter list would look like: 

   setRect( int newHeight, int newWidth ) ;
Java doesn't care what the parameter names are, just as long as no two names are repeated. It just cares about types.

Even so, we write descriptive parameter names, such as newHeight and newWidth, so people who use this method get additional information. They know to provide height and width information in that order. Order makes a difference. You need to provide the height first, then the width.

A Good Question

At this point, you might be wondering "OK, so this (fake) setRect method requires two values, height and width. How do I provide these values?"

This is a good question, but one we'll have to answer a little later. For now, pretend you have a card that you fill out. On the card, you write a method name (say, setHeight), and the height (say, 10). This card is given to the object, and it knows what to do with it.

We'll give the real details soon enough (though it's not all that different from what I've told you).

Methods with Parameter Lists

Some methods needs parameters, such as setHeight. It needs a height value. Some do not, such as getHeight which only retrieves information from the object. For methods that do not require any parameters, the parameter list is empty. It is written as ().

Let's fill out the rest of the parameter lists of all the methods.

Let's look at getHeight() (I'm adding parentheses so that it's easier to see that it's a method). Why doesn't it need any parameters? Recall that a method is a command sent to an object. The object stores some information. It can also do computations given the information it stores.

At the very least, a Rectangle object stores information about its own height and width. So, all the object needs to know is that we need the height, which is what the getHeight() method says.

Return Values

Sending a method (command) to an object is a two-step process. The first step sends the method, plus values that the method requires. The object then does any necessary computation given the method and values. This may change the internal information of an object (such as the height and width). Furthermore, the object can give back a value to the object user. The object user is the one who sends the method to begin with.

Let's think about that for a moment.

Consider the method getHeight(). This is a method sent to an object to ask for its height. We don't need to provide any additional parameters for this information. The object responds by providing its height.

This is called the return value.

Any method can have a return value. The only problem is that, unlike parameters, you can only have one return value. There are times where it would be convenient to return two or more values, and there are somewhat clumsy ways this can be done, but in general, you can only return back a single value.

Since Java cares about types, you must indicate the type of the return value.

It's possible that an object doesn't return anything to the object user. For example, if you are calling setHeight(), your intention is to change the object. You don't need anything back from the object.

When a method does not have a return value, the return type is void, which isn't really a type in the sense that there are no values of that type. Still, since Java requires a return type, we need to put something there even when there is no return value.

Method Signatures

We're now ready to talk about method signatures. A method signature consists of the following: Here's a sample method signature: 
int getHeight()
This consists of: This is the list of method signatures for the methods we've discussed. You'll notice the set methods have void return type and the get methods have non-void return type. That should make sense. When you get a value, you want some information from the object, so it has to return something.

When you set a value, you are giving information to the object, so there's no real need for a return value.

I should point out that you can create methods where you both provide information and the object gives information back. None of the methods above do this, but it's not unusual.

Should it be double?

You might wonder why the height and width are int. Would it make more sense for it to be double? Certainly, you could do this. A class designer must decide what they think the best types for quantities such as height and width. I happen to choose int.

As an exercise, rewrite the method signatures above assuming height and width are double instead of int.

Class Designer

As a class designer, you must think about what an object user wants from the object. You decide what methods the object user can use. You decide how these methods should behave. Once you've made these decisions, you provide a set of method signatures, plus some documentation explaining what each of the methods do.

In effect, the class designer is deciding what the object user can do. They give a list of methods, and promise that the methods work as advertised. It's similar to a remote control designer.

The object user uses the description of the class provided by the class designer, creates objects, and starts using them to solve the problems they want solved.

Method Signature Plus Documentation

Here's how the documentation might look to the user.

What's Missing

The method signatures (and documentation) is the view that the class designer gives to the object user. However, the class designer has more information that the object user doesn't know about.

Think about what's missing. How does a Rectangle object compute the perimeter? You may know the forula (two times the height plus two times the width), but do you see the formula anywhere in the method? You don't. Clearly, the class designer needs this information to fully write the class.

Also, there must be something storing information within the object. In fact, you should already be able to guess that an object has variables keeping track of the height and width.

For the most part, the object user doesn't have to think much about the code that makes the methods work, nor about the variables contained within the object.

As you learn about classes, it's best to learn it first from the object user's perspective, then from the class designer's perspective. This is just the same as for real world objects like remote controls. Should you learn how to design remote controls first, or learn how to use it first?

It makes sense to learn how to use it first, because then you can see the object as it's likely to be used. In any case, as a designer, you also have to know how you want the object to work, so think first from the object user perspective.

In essence, the object user is a customer, while the class designer is the provider, providing the customer with what they need, or usually what the class designer thinks the customer needs.