Java Concepts and Style;

Transcription

1 Java Concepts and Style; By Stephan Jossie Iowa State University

2 Variable Names Consider the two following code segments. The first is an example of bad variable names, while the second example is an example of code with good variable names. double a = 1000; double b = 0.08; int c = 20; for(int d = 0; d < c - 1; d++) a = a + a * (1 + b); Do you any idea what it s doing? Not likely. double capital = 1000; double interestrate = 0.08; int numberofyears = 20; for(int year = 0; year < numberofyears - 1; year++) capital = capital + capital * (1 + interestrate); What about now? You probably don t know exactly what it s doing, but you can at least now guess that it has something to do with computing interest of some sort. (It s actually computing compound interest). This is a great example of how bad variable names make code more confusing (also known as obfuscating), and how good variable names make self documenting code. Commenting Only about half of the code in this document contains comments in any form. That s because most of the code in this document is straight-forward enough that either common knowledge or a quick gander at the Java API will answer any questions about what is happening. Comments are important, however. Let s look at this code: public long method(int n) if (n == 0) return 1; long retval = n; for (int i = n; i > 1; i--) n -= 1; retval *= n; return retval; Not clear, huh?

3 Is it clearer what it is accomplishing if I add comments? Let s take a look. public long method(int n) // empty product is 1 if (n == 0) return 1; long retval = n; // compute n * (n-1) * (n-2) *... * (1) for (int i = n; i > 1; i--) n -= 1; retval *= n; return retval; It should be clearer now that the code is computing a factorial (in math notation that s: n!). Factoring out Common Code Let s take a look at a method that computes the n th Fibonacci number using the mathematical formula (as opposed to looping or recursion). F n = φn φ n 5 ; φ = A straight translation of the formula into code might look something like this: private static long getfibonaccinumber(int n) double phi = (1 + Math.sqrt(5)) / 2; return (long)((math.pow(phi, n)-math.pow(-phi, -n)) / Math.sqrt(5)); But hopefully you noticed that φ (phi) is constant. And hopefully you noticed that 5 is constant and you hopefully also noted that we calculated 5 twice. So why recalculate these values every time that you call fib? You could save some time (division and computing the square root (more so than division) are two math operations that are somewhat time intensive). So the code might look like this after extracting the constants: private static final double SQRT5 = Math.sqrt(5); private static final double PHI = (1 + SQRT5) / 2; private static long getfibonaccinumber (int n) return (long)((math.pow(phi, n) - Math.pow(-PHI, -n)) / SQRT5);

4 Now the values of 5 and φ are calculated when the class is first instantiated instead of every time the method is called (also final because they will never change). Sure this is a very trivial example and the benefit of doing these three statements outside of the method probably will have no discernable impact on the run time, but being able to see code that is common between multiple parts of a program will make it easier to implement those common functions in a way which they can be easily reused. Suppose that we had another function that required the use of φ, having already calculated it we can just use it in whatever methods need it. And if the definition of φ were to change, we d only have to change it in one place in our code instead of every time we used it. (Trivia: φ represents the golden ratio). Let s look at some other examples of code that could be reused. Take a likely implementation of some of the java.lang.string methods. Let s look at substring and its overloaded counterpart. Assuming that a String is implemented as a char[] a possible implementation is: private char[] characters =...; public String substring(int startindex, int endindex) // The length of the substring is the difference between the start and // end indices char[] substring = new char[endindex - startindex]; // Copies substring.length characters from the characters array // to the substring array. Starts at characters[startindex] // and copies to substring starting at substring[0]. // No need to do a for loop to copy the array since the Java library // already has a method that does array copying System.arraycopy(characters, startindex, substring,0,substring.length); return new String(substring); public String substring(int startindex) return substring(startindex, characters.length); You should see code reuse in the single-parameter version. All it does it call the two-parameter version with the same startindex but substituting the length of the char array in for the end index. We also avoided implementing our own array copying routine we simply used the one that the Java library provides. Let s take a look at a real-world program. This next segment of code is from a class that reads data from a database and stores it into an XML document. Consult chapters 22 and 23 of Big Java 3 rd Edition for more information on Databases and XML document manipulation in Java. (Comments and omitted for brevity; indentation not necessarily preserved to avoid excessive line wrapping where possible).

5 public class ThespianXMLDocument private DocumentBuilder builder; private Document doc; private ThespianDataset data; public ThespianXMLDocument() throws ParserConfigurationException DocumentBuilderFactory factory = DocumentBuilderFactory.newInstance(); builder = factory.newdocumentbuilder(); data = new ThespianDataset(); public Document build(arraylist<thespian> thesp) throws SQLException doc = builder.newdocument(); doc.appendchild(createthespians(thesp)); return doc; private Element createthespians(arraylist<thespian> thesp) throws SQLException Element e = doc.createelement("thespians"); for(thespian thespian : thesp) e.appendchild(createthespian(thespian)); return e; private Element createthespian(thespian thespian) throws SQLException Element e = doc.createelement("thespian"); e.appendchild(createtextelement("firstname", thespian.getfirstname())); e.appendchild(createtextelement("lastname", thespian.getlastname())); e.appendchild(createtextelement("gradyear", ""+ thespian.getgradyear())); e.appendchild(createtextelement("initiated", ""+thespian.isinitiated())); e.appendchild(createtextelement("totalpoints", "" + thespian.gettotalpoints())); e.appendchild(populateevents(thespian)); return e;

6 private Element populateevents(thespian thespian) throws SQLException ArrayList<Event> events = data.getevents(thespian.getfirstname(), thespian.getlastname()); Element e = doc.createelement("events"); for(event eve : events) Element event = doc.createelement("event"); event.appendchild(createtextelement("name", eve.geteventname())); event.appendchild(createtextelement("location", eve.geteventlocation())); event.appendchild(createtextelement("year", "" + eve.getyear())); event.appendchild(createtextelement("points", "" + eve.getpointsawarded())); e.appendchild(event); return e; private Element createtextelement(string name, String text) Text t = doc.createtextnode(text); Element e = doc.createelement(name); e.appendchild(t); return e; // End class ThespianXMLDocument The point of this code isn t to understand what it s doing, but rather the fact that code was broken up into smaller parts that deal with logically different parts of the constructing the document. This code could be written as one large method that simply createthespians constructs the XML document; however it is more logical to break it up into these five smaller units because each unit has its own designated purpose, which overall makes it much easier to read. We can see createthespian in the method createthespian, it creates an element, fills that element with name and other information, and then it defers to a method called createevent. CreateEvent creates an element populateevents that contains data for each event for that thespian. Graphically, the document is similar to the tree to the right. Each method points to an element in the tree that it would produce. CreateTextElement would create any element that is depicted by a gray dot. CreateThespians creates the root element Thespians. createtextelement

7 Blocks and Shadowing Consider the following code: if(...) int number = 7; System.out.println(number); // Will cause a compile-time error You get a compile error on the system-out. Why? Because number was declared inside the body of the if-statement. You cannot access variables that are declared inside of a block, outside of that block. The correct version of this code is below: int number = 0; if(...) number = 7; System.out.println(number); Consider this code (assume that we intended to have nothing printed; i.e. we expected 100%7 == 0 to be false): private int number = 100; public void dosomething() int number = 7; if(number % 7 == 0) System.out.println("Number is divisible by 7 evenly!"); What does it print? If you guessed Number is divisible by 7 evenly! then you re correct. Why? Well, it s because the declaration of number inside the method dosomething shadows the member variable of the same name. How do we fix this? We have two options: 1. Change the name of either variable 2. Use the this keyword when we want to access the member variable instead of the local variable

8 Using solution 1 (renaming; change is underlined): private int number = 100; public void dosomething() int localnumber = 7; if(number % 7 == 0) System.out.println("Number is divisible by 7 evenly!"); Using solution 2 (this keyword; change is underlined): private int number = 100; public void dosomething() int number = 7; if(this.number % 7 == 0) System.out.println("Number is divisible by 7 evenly!"); Often beginner programmers make the same mistake when they shadow instance variables with parameter variables as well. They might create the following code thinking that naming the instance and parameters the same name will somehow automatically set the instance variable. public class Test private int number; public Test(int number) However, this code actually does nothing except set number to 0 (because that s what Java does to ints that are declared as member variables; initializes them to 0). Eclipse implies that the member number and the parameter number are different by the way it highlights the variables Other programmers do the following, probably thinking that the compiler will know what they intended. public class Test private int number; public Test(int number) number = number; But this code does nothing as well. Basically it says to set number to itself (which Eclipse complains is a statement that has no effect ; which is only a warning of course, so it happily lets you compile some

9 code that won t do anything). In either case, the solution is the same as above: either rename one of the variables (perhaps add a p for parameter) or use the this keyword when you need to access the member variable. Try-Catch & Exceptions Whenever you use a method that throws a checked exception Java requires you to either place a trycatch block around it or to add a throws declaration to the header of the method in which you are using the method that may throw an exception. Some students try to make the compiler happy by doing the following: Scanner filein = null; try filein = new Scanner(new File("...")); catch(exception e) // BAD!! This isn t very good for at least two reasons. 1. Your program may run fine but if you try to use any Scanner method after the catch block you ll get a NullPointerException because a Scanner object was never made, thereby meaning that filein still is null. 2. This will catch any and every exception that is thrown inside the try block, even unchecked exceptions such as IndexOutOfBounds and InputMismatchException and exceptions that you may need/want to let the calling method deal with or maybe you just need to have it propagate all the way back to the JVM and have the program terminate. a. You should always use the most specific Exception type(s) for your catch block(s). And always put the most specific Exception type first. If the current method isn t appropriate for handling the exception, then add the throws declaration to the method and let the caller handle it. You should also resist the urge to place all of your code inside of a try-catch block. It s not good style to surround code that never throws exceptions in try-catch blocks it s misleading, potentially confusing, and doesn t force you to think critically about exceptional states in your program. For example, suppose you have a main method that gets a file from the user then prints the contents of the file to standard out. Part of this code will never throw an exception, while part of it may. You shouldn t include the part that won t throw the exception in the try-catch block unless it depends on the code that might throw an exception. See the following:

10 // Bad public static void main(string[] args) try //This covers code that will never throw a FileNotFoundException Scanner stdin = new Scanner(System.in); Scanner filein = null; // Get user input (the user types a file name on each line) while (stdin.hasnextline()) // make a new file with the next file name File f = new File(stdin.nextLine()); filein = new Scanner(f); // output the contents of the file while (filein.hasnext()) System.out.println(fileIn.next()); // if the scanner was successfully created...close it when // we're done if (filein!= null) filein.close(); stdin.close(); catch (FileNotFoundException e) System.err.println("The file was not found. " + e.getmessage()); // Good public static void main(string[] args) Scanner stdin = new Scanner(System.in); Scanner filein = null; // Get user input (the user types a file name on each line) while(stdin.hasnextline()) // make a new file with the next file name File f = new File(stdin.nextLine()); try // This covers the code that will likely throw an exception filein = new Scanner(f); // output the contents of the file while(filein.hasnext()) System.out.println(fileIn.next()); catch(filenotfoundexception e) System.err.println("The file was not found. " + e.getmessage()); // if the scanner was successfully created...close it when we're // done if(filein!= null) filein.close(); stdin.close();

11 When reading from a file (or other similar tasks) where you cannot handle the exception, you should still do some cleanup after an exceptional event occurs. See the following code for an example. public void writestuff(string[] towrite) throws IOException, FileNotFoundException // Create a new PrintWriter; You may notice that PrintWriter s // constructor throws a FileNotFoundException and yet it s outside of // the try-finally...why? Because if we place it inside the try, we // cannot access it in the finally block, as we saw earlier in the // shadowing examples (and we re going to let the exception be thrown // anyway since we have no catch block) PrintWriter out = new PrintWriter("path"); try // write some stuff to file finally // happens whether or not an exception is thrown // Close the PrintWriter whether or not an exception was thrown. // We have no risk of generating a NullPointerException because // at this point we are guaranteed that a PrintWriter was created // (since if the constructor threw the FileNotFoundException // we could not have made it to this point in the code) out.close(); Any statements in the finally block execute whether or not there is an exception, which is good. If there was an exception while writing the file, then we no longer need to keep the file open as we cannot continue to write to it. Conversely, if we re done writing the file and it was successfully completed, we no longer need the file open since we don t have anything else to put in it. Absolute vs. Relative File Paths Let s say that your program needs to access files in a subdirectory and you know that your directory structure looks like the tree (gray dots are files) to the right. The current working directory is the directory from which your program is being executed, therefore you may use relative paths to access anything in the subdirectories. So if I were running this program on Windows I would be able to simply access the Text.txt file using the following line of code: File textfile = new File("Test Folder\\Text.txt"); You might be wondering if the above line of code is specific to one machine. Nope. When you create a File object in java it normalizes the path, that is (among other things) it parses the path and changes any file path separators to the correct one for the current operating system. In the above code, if running

12 on a Unix system (OS X or Linux, for instance) then all of the \\ will be replaced with / which are the correct file path separators for the system. Likewise if it contained / and was run on a Windows system then all of the / will be replaced with \\. Do note though that case is important on most (all?) Unix based systems: Text!= text. // On Windows, the following line prints the string "Test Folder\Text.txt" // On Unix systems (Mac, Linux, etc) "Text Folder/Text.txt" System.out.println(textFile.getPath()); Why should you use relative paths? Well suppose I stored my program on my Windows desktop (which has a path of C:\users\stephdogg\desktop). To access the text file from above using an absolute path I would need to say the following instead: textfile = new File("C:\\users\\stephdogg\\desktop\\Test Folder\\Text.txt"); Now, let s say that I gave the file to my friend who knows nothing about programming. Would he be able to run it from his desktop with path C:\users\friend\desktop? No, he wouldn t if I had used the absolute path. What if I gave it to someone running on a different operating system? Would Linux Friend be able to use it from his desktop (which has a path of /home/linuxfriend/desktop)? Nope, he couldn t either. This demonstrates that you can t always know the exact path to the location of files you need. However, assuming that your program was installed correctly you can know where the files you need are relative to the program. When we use the relative path above (TestFolder\Text.txt) we can access the correct file. File textfile = new File("Test Folder\\Text.txt"); System.out.println(textFile.getAbsolutePath()); // On my computer this prints C:\users\stephdogg\desktop\Test Folder\Text.txt // On my friend s computer C:\users\friend\desktop\Test Folder\Text.txt // On Linux Friend s computer /home/linuxfriend/desktop/text Folder/Text.txt Path Separator Characters Remember our little tangent earlier about the File object correctly deducing our path even when we had the wrong file path separator characters (/ instead of \\ or vice-versa)? Well in order to guarantee that we have the correct file separator we should use one of the File object s handy constants. Using our text file from above and the more appropriate way of setting its path, our code would look like this: File textfile = new File("Test Folder" + File.separatorChar + "Text.txt"); Note the File.separatorChar where the double slash was before. This File.separatorChar is replaced with the correct file path separator for the operating system that the program is being run on. // On Windows, the following line prints the string "Test Folder\Text.txt" // On Unix systems (Mac, Linux, etc) "Text Folder/Text.txt" System.out.println(textFile.getPath());

13 Special note: you may notice that there are four similar looking constants in the File object: pathseparator pathseparatorchar separator separatorchar The first two (pathseparator and pathseparatorchar) are semicolon on Windows and colon on Unix based systems. These are use in the path variable that describes the location where the operating system searches for commands (definition from IBM). While the latter two (separator and separatorchar) are the actual character that is between folder names and file names you would use separator or separatorchar when you are specifying file paths. The String versions are there simply for convenience.