Date post: | 02-Jan-2016 |
Category: |
Documents |
Upload: | annabelle-parsons |
View: | 217 times |
Download: | 1 times |
Question of the Day
On a game show you’re given the choice of three doors: Behind one door is a car; behind the others, goats. After you pick a door, the host, opens another door which has a goat. He then asks, "Do you change your selection?” Should you?
javadoc
Program included with all Java compilers
Automatically generates web page for class Requires specially formatted comments Methods, constructors, & fields described
on page Makes using classes much, much simpler Very little work required to start Getting good at it requires lots of practice
javadoc Comments
Comments are located between /** & *//** This is a javadoc comment */
Two parts to any javadoc comments First is the description then any tags
Description of the member Descriptions can contain plain text and/or
HTML Features documented using tags in javadoc Example of features: parameters & return
value Tags start with @TagName then follow tag's
pattern
javadoc Descriptions
1st sentence summarizes the comment Ends at first period followed by whitespace Web pages prints summaries in upper area Should be concise, but complete
description Lower area of page has full description
Includes summary sentence Also lists information from tags
javadoc Tags
@author Author Name[, Author Name, …] Can only be used within class documentation Can use multiple @author tags
@return Description Use to describe value method returns Plain text and/or HTML can be used as
description
@param ParamName Description Should include a tag for each parameter ParamName identical to parameter name Description can be in plain text or HTML
What To Say In javadoc
Class What the class does How it should be used Use @author tags to list authors
Fields Value stored in the field How field will be used Assumptions about field’s value Important values field may have
What To Say In javadoc
Constructor/Methods How to use this method Results of calling this method Any other important details Use @param to state what inputs should be Use @return to explain the value is
returned Do NOT describe how it actually
works
More about comments
javadoc is MINIMAL set of comments needed Methods should also include normal
comments Normal comments describe how method
works Comments can help explain why method
works Makes your life easier when debugging!
Packages
All classes reside in a package Declared at start of class file: package pkgName;
Classes in default package if not specified Package part of full name of class
Within a package, class names must be unique Between packages can reuse class names Some classes usable without full name
Cannot import classes in default package These classes are nearly useless
Why Use Packages?
Simplify organization of classes Each package has small set of related
classes Can nest packages (e.g., java.util) Enables creating hierarchy of related
classes Limits knowledge needed by
programmer Java programs use 1000s of classes How many of these do you know?
Real-Life Debugging Story
System crashed when field was null 145 assignments in 100,000+ LOC
1 out of 145 did not check for null Took 2 weeks to find & fix bug
Remembered class & its field’s issues Saved time figuring out bug Ultimately, I got lucky to fix this
Preventing bug is clear goal
Visibility Modifiers
Specify usage of classes, methods, or fields
Each modifier has different purpose private – Access within same class (file)
only protected – Use anywhere in package or
subclass public – Use at anywhere & at any time package – Lazy developer did not type a
modifier
Prevent the Nightmare
Everyone tries keeping certain details private What is exposed is limited Limit how & why changes occur
Prevent the Nightmare
Everyone tries keeping certain details private What is exposed is limited Limit how & why changes occur Stop others from seeing changes
Prevent the Nightmare
Exact same holds for objects Make fields private unless for very
important reason:private int fieldName;
Limits errors since field accesses entirely in 1 file
Improves modularity of your program Makes object-oriented programs easier to
write
Accessor Methods
Gets field’s value in another class Getter methods useful, but not special
Named getField or similar in most casespublic fieldType getField() {
Other classes must use accessor method Easily limit access by adding check for
password Searching for field’s uses is also simple
Mutator Methods
Sets field’s value from code in another class Like getters, just another method
Named setField normallypublic void setField(fieldType param) {
All field changes normally via mutator Updates can be checked to insure value is
legal Number of ways creating bugs is limited
Visibility of Methods
Methods normally act on or with object Use active verb as name Declare as either public or protected
Replace copies of code with single method May have common test, calculation, &c. Work is internal to how class performs tasks These methods should be private Simplifies coding & debugging this class
Access Protection Benefits
Enforce constraints on object's state Amount of javadoc limited
Can use any comments for private members
Provide simple client interface Abstraction:
Make available only what people must know
Encapsulation:Separate interface from
implementation