Variable Scope & Lifetime CS 161 February 11, 2000

Overview A few more words about Program #3 JavaDoc Variable Scope

Program #3 Some Changes Some Clarification Some Removals Draw half bar may be special case of drawing full bar Some Clarification Methods are required Documentation for methods are required Some Removals Do not turn in JavaDoc generated files

Software Development Software Engineering Java to the Rescue Documentation Documentation is hard to keep accurate & up to date The source code is the best source of documentation Java to the Rescue Well, a program included with the Java Development Kit (JDK) JavaDoc Reads Java source code and produces documentation

JavaDoc JavaDoc is a command line program which extracts comments from Java source code and formats them into HTML pages Works on public packages, classes, interfaces, methods & variables Also protected methods & variables Extracts comments which begin with /** And Special Keywords

JavaDoc General Tags @since text @deprecated text @see link Where text is a description of the version which introduced this feature @deprecated text Where text is a description of methods which you plan on making obsolete in a future release. You should suggest an alternative @see link Where link is text or an HTML reference tag <a href="otherpage.html">label</a>

Class & Interface Tags @Author Name @Version text Where Name is your (or the program author's) name. You may want to include an email address or a company home page @Version text Where text is a description of this version of the source code

Method Tag @param @param variable description Where variable is one of the formal arguments in the following method The description is a description of what the variable is used for, any restrictions or limitations expected or enforced (e.g. range). It’s not a bad idea to include type information The descriptions provided as examples in the textbook are anemic All of the param tags for a given method need to be grouped together in the same comment without intervening tags.

Method Tag @return @return description @throws class description The description you provide should indicate what the return value is, what it can be used for, special values, units, and so on. @throws class description If your class throws an exception (which must be handled inside of a try-catch block), you would describe it with this tag.

An Example Program Program Fac.java /** A Java Application to demonstrate factorials @author Cay Horstman @version Computing Concepts w/ Java 2 Essentials 2nd Ed @see <a href="http://www.cs.orst.edu/~nsmith/cs161/win00"> For CS 161, Winter 2000</a> */ public class Fac {

Factorial Program, Continued /** The main method is where execution starts. It instantiates a ConsoleReader object to get interactive input from the user. It calls the recursive <B>factorial</B> method. @param args An array of strings consisting of the words on the command line. <I>These are ignored</I> */ public static void main(String[] args) { ConsoleReader console = new ConsoleReader(System.in); System.out.println("Please enter a number:"); int n = console.readInt(); System.out.println(n + "! = ” + factorial(n)); }

Factorial Program, Continued Program Fac.java (continued) /** Recursively computes the factorial of an integer. @param n an integer >= 0 @return n! <I>(if n is out of bounds, a 1 is returned)</> */ public static int factorial(int n) { if (n <= 0) return 1; else int result = n * factorial(n - 1); return result; }

Program Fac.java (continued) /** Computes the factorial of an integer. @param n an integer >= 0 @return n! */ public static int factorial(int n) { if (n == 0) return 1; else int result = n * factorial(n - 1); return result; }

Running JavaDoc Z:\CS161\Factorial\docs>javadoc Factorial.java Loading source file Factorial.java... Constructing Javadoc information... Building tree for all the packages and classes... Building index for all the packages and classes... Generating overview-tree.html... Generating index-all.html... Generating deprecated-list.html... Building index for all classes... Generating allclasses-frame.html... Generating index.html... Generating packages.html... Generating Factorial.html... Generating serialized-form.html... Generating package-list... Generating help-doc.html... Generating stylesheet.css... Z:\CS161\Factorial\docs>

Java Variables Variables in Java can be ether primitives or objects (based on classes) We can divide variables into 4 groups Instance (Class) variables Static Variables Local (method) variables Parameter Variables

Variable Lifetime The lifetime of a variable describes the time A variable is created Through the time that it is destroyed And that storage is available for re-use When an object is constructed (instantiated) All instance variables are created They are initialized according to their declaration statements The position in the Java source code is relatively unimportant It does start at the top and go to the bottom

The Duration of a Variable's Lifetime When the object which created the object is no longer useable The method that created it ends All reference to that object are gone The variable is disposed And the storage space is available for other variables

Static Variables When a class with static variables is referenced for the first time All static variables are created Any initialization is performed When the object which loaded the static class is no longer needed (which is hard to tell) The static variables of that class are destroyed

Parameter Variables Parameter variables are the variables based on the formal arguments to a method These are always copies of the value of primitive values declared elsewhere Or values from expressions These remain 'in scope' throughout the lifetime of that method call They are recreated with each method call

Local Variables These are variables declared within a method Or other code block e.g. for ( int j = 0; … ) { … } It exists only within that code block

Initialization All instance variables are automatically initialized 0 for numbers false for boolean null for objects unless we specify otherwise Parameter variables are initialized with copies of their actual arguments

Key ideas Lifetime (duration) Scope Shadow Alias When the variable (or object) exists in your program Scope Where the variable can be used Shadow When the scope of one variable takes precedence over another of the same name Alias The same object is referenced by two different names

Overview / To Do Program #3 JavaDoc Variables Monday Wednesday Friday Kinds instance, static, parameter & local Lifetime/Duration Scope Shadowing Aliases Monday Testing & Debugging Wednesday OOP & Class Design Program #3 Due Friday Inheritance Quiz #4 WS #4 & HW #5