CPSC 124, Fall 2005
Lab 6: Writing Subroutines

Since almost the beginning of the course, you have been using subroutines written by other people. You have also been filling in the inside (that is, writing the implementation) of subroutines such as main and paint. In today's lab, you will be writing complete subroutines from scratch. You will also be introduced to "javadoc" comments.

To begin the lab, you should start up Eclipse and begin a new project named "Lab 6". Import the files StringSubs.java and TextIO.java into your project. You can find copies of these files in the directory /classes/f05/cs124/lab6. The StringSubs program has a main routine, but this routine contains several references to subroutines that don't yet exist. Your task in this lab is to define the missing subroutines.

To see what the completed program will do, you can open a command window, change to the directory /classes/f05/cs124/lab6 and run the program StringSubsComplete, using the command java StringSubsComplete. The program lets you enter lines of text and apply simple string-processing operations to the strings that you enter. Your completed program should work in pretty much the same way as StringSubsComplete.

There is no lab next week, because of Fall break. This lab is due in two weeks, on Tuesday, October 18. Turn in a printout of your program at that time.

Writing Subroutines

You are already familiar with several features of subroutines. A subroutine has a name. It can use parameters, such as the "x" in System.out.println(x). And, in the case of a function such as Math.sqrt(x), it can have a return value. The syntax for writing a subroutine is covered in Section 4.2. Here is a simplified version for this lab:

          private  static  <return-type>  <subroutine-name>  ( <parameter-list> ) {
              <statements>
          }

The <return-type> specifies the type of value that is returned; for a subroutine that is not a function, the <return-type> is given as void. The <subroutine-name> is the name that will be used to call the subroutine. And the <parameter-list> specifies what parameters must be provided when the subroutine is called. For example, the first line of the subroutine getUserCommand is:

         private static int getUserCommand() {

Here, the <return-type> is int since this is a function that returns as integer. The <subroutine-name> is getUserName. And the <parameter-list> is empty, meaning that no parameters are required to call this subroutine. In the main program, the subroutine is called in the statement "menuChoice = getUserCommand();", where menuChoice is a variable of type int. Note that no parameters are included in the function call, and that the integer value that is returned by the function becomes the new value of menuChoice.

The code inside getUserCommand presents a menu to the user and reads an integer that is typed by the user. That integer becomes the return value. This is specified by the command

         return choice;

at the end of the function. Every function must use a return statement to return the value of the function.

Given this much information, you should be able to write the function named readUserInput. This subroutine has an empty parameter list, and it has a return type of String. The subroutine should ask the user to enter a line of text, and it should read the user's response into a String using the function TextIO.getln(). That variable then becomes the return value of the function. Write the function, make sure that it contains no errors, and make sure that the errors on the statements "lineOfText = readUserInput();" in the main program go away. You might also want to write a Javadoc comment for your subroutine at this time; see the final section of this page for information on how to do that.

The next step is to write a subroutine that has a parameter list. The countChars subroutine will count the number of occurrences of a given character in a given string. To do this task, the subroutine obviously needs to know two things: the string and the character. These are the parameters. The definition of the subroutine must specify that there are two parameters, of type String and char. Each parameter also has a name. These names are like variables that can be used in the definition of the subroutine; they differ from variables in that they don't have to be assigned initial values -- they get their initial values when the subroutine is called. Here is the first line of the definition of countChars:

          private static int countChars(String lineOfText, char charToCount) {

You can copy this into your program; you just have to write the body of the subroutine. Note the syntax used for specifying the type and the name of each parameter. The subroutine should count the number of times that charToCount occurs in the string lineOfText. That is pretty easy; we've done it as an example in class. The answer should be returned in a return statement at the end of the subroutine.

There is just one more variation that you need to be aware of. If a subroutine is not a function, then its <return-type> is specified as void. (This special word indicates an "empty" return value.) The only "void" subroutine that you have to write for this assignment is printLetterCounts. The first line of this subroutine is:

          private static void printLetterCounts(String lineOfText) {

The return type is specified as void, and there is one parameter in the parameter list. Again, you can copy this line into your program, and then write the body of the subroutine. The purpose of the printLetterCounts subroutine is to print a table that shows the number of times each letter from 'a' to 'z' occurs in the string. Don't forget to count both the upper-case as well as the lower-case form of each letter. You might find the built-in function Character.toUpperCase(ch) to be useful; this function returns the upper-case form of the character ch. Since printLetterCounts is a "void" subroutine, there is no value to return, and so you don't need to include a return statement in the body of the subroutine.

You should have enough information about subroutine syntax to complete the remaining three subroutines, countWords, isPalindrome, and expurgate. You still need some information about the semantics and some hints about how to write them:

• countWords -- has one parameter, of type String, and a return value of type int. The return value is the number of words in the string. A "word" here simply means a sequence of letters (even though this counts some things as words that are not really complete words). To count words, note that a character is the beginning of a word if and only if (1) it is a letter and (2)  it is either the first character in the string or the preceding character is not a letter. This gives a straightforward test that you can apply to each character in the string, and count the number of characters for which the test is true. You can use the built-in function Character.isLetter(ch) to test whether a character is a letter.
• isPalindrome -- has one parameter, of type String, and a return value of type boolean. The return value should be true if the string is a palindrome and should be false if it is not. A palindrome is a string that reads the same backwards and forwards. We discussed in class how you can test this in Java. Ideally, upper and lower case letters should be considered equivalent, and all characters that are not letters should be disregarded; however, you should probably not worry about this detail until you have the rest of the lab working.
• expurgate -- has one parameter, of type String, and a return value that is also of type String. The return value should be a copy of the parameter, except that the naughty words "heck" and "darn" (and any others that you care to handle) should be censored: "heck" should be replaced by "h**k" and "darn" should be replaced by "d**n". This would be quite difficult, except that there is a built-in String subroutine that does just what you need. If str is a variable of type String, then str.replaceAll("heck","h**k") is a function that returns a copy of str in which each occurrence of "heck" has been replaced by "h**k". (I included expurgate largely just to give you an idea of some of the things that Java can do with strings.)

Writing Javadoc Comments

"Javadoc" is a system for creating documentation for Java programs, in the form of Web pages. The documentation is created based on special comments, called javadoc comments, in the source code of the programs. A javadoc comment begins with the three-character sequence /** and ends with */. By convention, each line in the comment begins with a *, although this is not a requirement; these *'s are discarded before the content of the comment is processed. Each Javadoc comment is associated with a particular element of the program, such as an entire class or a subroutine. The Javadoc comment for a class as a whole must come just before the beginning of the class. The Javadoc comment for a subroutine must come just before the beginning of the subroutine. Member variables (that is, variables declared in a class but outside any subroutine) can also have Javadoc comments, but local variables cannot.

The text in a Javadoc comment will be shown on a Web page. The language used for creating web pages is called HTML, and Javadoc comments can include HTML commands. Usually, this is not important, but there are a few things you should know. For example, <p> can be used to separate paragraphs, and text that should appear in italics can be surrounded by <i> and </i>. One important consequence of the syntax of HTML is that the characters <, >, and & have special meanings in HTML. If you want these characters to appear on the Web page, you must express them as &lt;, &gt;, and &amp;, respectively.

A Javadoc comment should always start with a fairly short descriptive sentence. The first sentence is used as a summary description. The comment can then go on to give a fuller description of the class, subroutine, or variable that is being commented. After this descriptive text, the comment can include certain tags that describe, for example, the parameters and return value of a subroutine. A parameter description tag takes the form

             @param <param-name> <param-description>

and the tag that describes the return value of a subroutine takes the from

             @return <return-value-description>

Eclipse offers some help with writing Javadoc comments. To write a Javadoc comment for a subroutine, position the cursor just above the start of the subroutine, type the /** that begins the comment and press return. Eclipse will create an outline of the comment, including the @param tags and, if the subroutine has non-void return type, the @return tag. You just have to fill in the descriptive text. Also, as you type, Eclipse will insert the leading *'s for you.

As part of your work for this lab, you should write a Javadoc comment for each of the six subroutines that you write. The one subroutine that was already written has a comment that can serve as an example.

Eclipse can create documentation web pages based on the javadoc comments in your code. Just right-click the project name in the area on the left side of the Eclipse window, and select the "Export" command from the pop-up menu. In the dialog box, select "Javadoc" as the type of Export, and click "Next". You will need to make just one change in the next screen: Under "Create Javadoc for members with visibility:", change the setting from "Protected" to "Private". (Ordinarily, Javadoc does not create documentation for private subroutines, since they are, after all, not meant to be public. However, in this case, your subroutines are private, so to see the documentation, you have to tell Javadoc to process private class members.) Then, click "Finish". The documentation will be created and will appear in a folder called "doc" in your project. Open the folder (by clicking the small triangle next to it), and double-click index.html to see the documentation that has been created for your project.