A value method is a method that returns a single value back to the calling code. The returned value needs to be either stored using a variable or used in a larger expression; for example, displayed using printf(). Just like void methods, value methods can accept zero or more parameters. Consider the following example:
|
1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23 24 25 26 27 28 29 |
import java.util.Scanner; public class ValueMethods { // This is our mainline logic for this program public static void main( String[] args ) { int numberOfStars = howManyStars(); System.out.println( "Here's " + numberOfStars +" stars:" ); displayStars( numberOfStars ); } // Prompt the user for how many stars they'd like and return it public static int howManyStars() { int howMany; Scanner input = new Scanner( System.in ); System.out.print( "How many stars would you like: " ); howMany = input.nextInt(); return howMany; } // This method accepts as a parameter the number of stars to display // (howMany) as an integer, and displays that many *'s to System.out public static void displayStars( int howMany ) { for (int stars = 0; stars < howMany; stars++) { System.out.print( "*" ); } System.out.println(); } } |
How many stars would you like: 7
Here’s 7 stars:
*******
The value method howManyStars() is defined on lines 12 to 19. As you can see, it’s similar to our void method defined on lines 23 to 28 with two key differences. First, in the method signature, instead of the keyword void is the data type of the value that the method will return, in this case int. Second, on line 18, to exit the method and return an integer value we use the return keyword followed by a matching int variable or value.
Notice how the method is called on line 6 using an assignment statement. On the right side of the = we are calling the howManyStars() method. This method gets an integer value from keyboard input and the return statement on line 18 passes it back to the calling code on line 6. That returned value is then assigned to the numberOfStars local variable in main().
The return Statement
Although not shown in the example code, it’s possible to have more than one return statement within in a method, each returning a different value. For example, you might have an if..else statement within a method that can return one of two different values. Just be aware that as soon as a return statement is encountered, the method will exit.
But wait.. there’s more! The return statement can be also be used with void methods! You can think of the return statement for void methods like a break statement for loops. In this case you can use the return; statement by itself (no variable or value after it) to cause the void method to exit and continue execution from where it was called. Here again you can have more than one return statement within a method if your algorithm requires it.
Method Commenting
Now that you know how to create void and value methods, let’s talk about how to properly comment them. Commenting within your code is called internal documentation. Internal documentation is useful to other programmers to help them read, understand, and maintain your code in the future.
Whenever you create a method you should always include a multi-line /* comment */ before the method signature that clearly explains: (1) the purpose/description of the method, (2) any parameters it requires (if any), and (3) any value it returns (if any). Even if the method is very short, and even if you think it’s self-explanatory, make an effort to comment it!
Javadoc Creation
External documentation is information about code in a form that is separate from the actual source code. The Java API is a perfect example of external documentation in the form of a nicely formatted collection of HTML documents. These are referred to as Javadocs.
You can easily create Javadocs for your own code with the click of a button, as long as you follow a few commenting conventions. Here is an improved version of the code above using Javadoc style comments:
|
1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23 24 25 26 27 28 29 30 31 32 33 34 35 36 37 38 39 40 41 42 43 44 45 46 47 48 49 50 51 |
import java.util.Scanner; /** * This class demonstrates basic <b>JavaDoc</b> creation. * * @author Vik-20 * @version July 1, 2016 */ public class JavadocComments { /* * This is the main() method, nothing fancy. * (Note: this comment is ignored by JavaDoc) */ public static void main( String[] args ) { int numberOfStars = howManyStars(); System.out.println( "Here's " + numberOfStars +" stars:" ); displayStars( numberOfStars ); } /** * This method uses a Scanner object to prompt the user * for how many stars they'd like and returns this as an * integer value. It takes no parameters. * * @return int - The number of stars requested * * @see Scanner */ public static int howManyStars() { int howMany; Scanner input = new Scanner( System.in ); System.out.print( "How many stars would you like: " ); howMany = input.nextInt(); return howMany; } /** * This method accepts as a parameter the number of stars to display * as an integer, and displays that many *'s to System.out. * It does not return a value. * * @param howMany The number (int) of stars requested */ public static void displayStars( int howMany ) { for (int stars = 0; stars < howMany; stars++) { System.out.print( "*" ); } System.out.println(); } } |
Don’t focus on the code here, focus on the commenting. All Javadoc comments use the multi-line comment, with one important difference – the opening part of the comment includes a double star (/**). If a comment does not start with this, or is a single-line comment (//) then the comment will not be included in your Javadocs. This can be useful because we often don’t want all of our comments included in our Javadocs.
Within a Javadoc comment there are also special tags that you can use. For example, these two are useful in a header comment at the top of your program:
It’s important to note that if you have any import statements in your Java code, they must go before the header comment for the header comment to be included in your Javadocs.
These tags are useful for method Javadocs:
There are a few other special tags, but these will suffice for our purposes.
To actually generate your Javadocs, you simply load your source files into Dr. Java and then click the 
button at the top-right of the window. By default, the Javadocs for your code will be generated in a folder called “doc” in the same directory as your code.
Click here to see what the Javadocs look like for the example above.
Wow, HTML formatted to look just like the Java API! This is just one more reason to love Java eh? You can also include HTML tags in your Javadoc comments — did you spot the <b> tag in the header? But don’t go overboard with this because it can make your internal documentation harder to read.
You Try!
- The Math class includes a method called pow() to calculate exponential values. Write your own version of this method using a loop, and call it iterativePower(). Your method should take an integer base and exponent as parameters and return the base raised to the exponent. For example, iterativePower( 3, 4 ) should return 81. Do not use any Math class methods. Write a main() method to demonstrate your method.
- A value method that returns a boolean value is called a boolean method. Style-wise, the names of these methods should sound like questions. Write a boolean method called isMultiple() that accepts a two integer parameters and returns true if the second integer is a multiple of the first, or false otherwise. Write a main() function to demonstrate how it works.
- Write a boolean method named isTriangle() that takes three integers as arguments and returns either true or false, depending on whether or not you can form a triangle from sticks with the given lengths. Hint: For any three lengths, there is a simple test to see if it is possible to form a triangle: If any of the three lengths is greater than the sum of the other two, you cannot form a triangle.
- Pick one of your solutions above and add Javadoc style comments to it. Try generating the HTML.