Project 1 Discussion and Documentation

1
Project 1 Discussion and Documentation
2
Algorithm for Main class
3
Structure of Report class
-inFile -grantTotal -genreCount -currentBook,
nextBook -newGenre -maxTotalGenre -maxGenre
FileInput
Fields
Book
Report object
printReport -processBook -processGenre -columnHea
dings -padL -padR
Methods
4
Algorithm for printing a report (Report.java)
Open file
Print footer of the report
processing a book
5
Algorithm for process a book and a genre
currentBook record just read Current genre
genre of the current book
Start a new genre and go back to processing a new
genre
6
Documentation

• Source code documentation is a fundamental
  engineering practice critical to efficient
  software development. Regardless of the intent of
  its author, all source code is eventually reused,
  either directly, or just through the basic need
  to understand it. In either case, the source code
  documentation acts as a specification of behavior
  for other engineers.

Without documentation, they are forced to get
the information they need by making dangerous
assumptions, scrutinizing the implementation, or
interrogating the author. These alternatives are
unacceptable. (http//www.literateprogramming.com/
quotes_sc.html)
7
Some examples

• Mysql 5.0 server documentation
• Documentation for String class in Java
• Documentation for JOptionPane class in Java
• GNU documentation

8
Questions for us
How can we generate a similar document for our
own class?
How can we make our code more readable?
9
Javadoc tool

• generating Application Program Interface (API)
  documentation in HTML format from doc comments in
  source code.
• Resource
• http//java.sun.com/j2se/javadoc/

10
What we focus on in this course

• How to write simple doc comments for Javadoc?
• How to run Javadoc

11
Template for Class Definition
Import Statements
Class Comment

Class Name
public class
Data Members
Methods (incl. Constructor)

12
Template for Class Definition
Import Statements
Class Comment
A doc comment must precede a class, data
members, constructor or method declaration

public class
Class Name
Data Member Comments
Data Members
Methods Comments
Methods (incl. Constructor)

13
Class comment

• First sentence should be a summary sentence,
  containing a concise but complete description of
  a class.
• The remaining of the class comments should talk
  about the purpose of this class

14
Example

• String class in Java
• JOptionPane class in Java
• Our Lab 2
• / This class provides various routines to
  convert metric measurements to U.S. units and
  vice versa. /

15
Data member comments

• / data members description
• /
• public ltdatatypegt ltfield namegt
• Note The documentation is only generated for
  those methods/fields that are declared as public

16
Example Our Lab 2

• /A factor to convert inches to centimeters /
• public static final double INCHES_TO_CENTIMETERS
  2.54
• / A factor to convert centimeters to inches /
• public static final double CENTIMETERS_TO_INCHES
  1 / INCHES_TO_CENTIMETERS
• / A factor to convert feet to inches /
• public static final double FEET_TO_INCHES 12.0

17
Result
18
Result
19
Constructor/Method comments

• Purpose what this method is doing
• Data (parameters, what they are) and
• Details description of data (parameters name,
  their data types)

20
Example

• / Converts a given length in inches to
  equivalent centimeters.
• _at_param inches the length expressed in
  inches
• _at_return length expressed in centimeters
• /
• public double inchesToCentimeters( double inches
  )
• //end inchesToCentimeters

21
Results

22
Writing Doc comments

• Block tags
• _at_param (classes, interfaces, methods and
  constructors only)
• _at_return (methods only)
• _at_exception (_at_throws is a synonym added in
  Javadoc 1.2)
• _at_author (classes and interfaces only, required)
• _at_version (classes and interfaces only, required.
  

23
Required tags

• _at_param ltname of parametergt ltdescriptiongt
• For example
• public void writeToFile(String fileName)
• _at_param fileName this represents the name of the
  file created for writing purpose.

24
Require tags

• _at_throws ltexceptiongt ltdescriptiongt
• Example
• public void writeToFile(String filename, int
  array) throws IOException
• _at_throw IOException if any error happens during
  the process of writing to a file.

25
Required tags

• _at_author ltname of authorgt
• _at_version ltversion numbergt, ltdategt

26
Required tags

• _at_return     ltdescription of the item returnedgt
• Note Omit this for constructors and void methods
• Example
• public void writeToFile(String fileName) ???
• public boolean readFromFile(String fileName)
• _at_return a boolean value (true/false) if there is
  no error/or any errors during reading process.

27
Example

• /
• What do I write here?????
• /
• public void readFromFile(String filename) throws
  IOException
• / Assuming data read is stored in an integer
  array /..

28
Example

• /
• Purpose read data from a file given a file
  name and store data in an integer array
• _at_param filename represents the name of file
  from which data is read
• _at_throw IOException if any error happens during
  the process of reading data from this file.
• /
• public void readFromFile(String filename) throws
  IOException
• ..

29
How to run Javadoc

• Step 1 Make sure you have javadoc installed
• Step 2 Command line mode
• change to the source directory
• type
• javadoc -d ltdocumentation directorygt package
  name
• Or
• javadoc -d ltdocumentation directorygt ltjava file
  namesgt

30
Lab 3

• Step 1 Open eclipse and your MetrixConverter.java
  class.
• Make sure this class is declared as public.
• Insert comments for feetAndInchesToCentimeters
  method
• Step 2 Open your Main.java (done in Lab2)
• Insert class comment for Main.java
• Insert data member comments (if applicable)
• Insert method comments for other methods (if
  applicable)
• Step 3 Using javadoc, generate documentation for
  this two classes

31
Documentation (continue)
How can we generate a similar document for our
own class?
How can we make our code more readable?
32
Documentation

• Comments along the code
• Create meaningful variable names
• Example
• public class DataProcessing
• Vs
• public class DiscountedLoan

33
Documentation

• Create meaningful variable names
• int h1, h2
• for (int i0 iltlengthName i)
• Define constants
• public static final double INCHES_TO_CENTIMETERS
  2.54

34
Arrays

• Array is a collection of data values of the same
  data type.
• Example
• int number // This is an array of integers
• double gpa // This an array of double

35
Array Declaration

• Format
• ltdata typegt ltarray_namegt
• OR
• ltdata typegt ltarray_namegt
• data type double, int, float, string
• Example
• double gpa
• Or
• double gpa

36
Arrays

• The amount of memory allocated to store an array
  depends on the size and type of values in the
  array
• Size number of elements in the array
• Type of values data type of each element in the
  array
• An individual value in an array is called array
  element
• Example
• int number new int5
• data type integer (4 bytes)
• size 5
• memory 20 bytes

Array is a reference data type. Array is NOT an
object
37
Arrays

• Example
• int number new int5

number0
number
6
1
2
3
0
4
38
Arrays

• Elements of an array are indexed from zero to
  number of elements in an array -1
• length a public constant represents the size of
  an array.
• Example
• sum 0
• for (int i0 iltnumber.length i)
• sum numberi

39
Fixed size array declaration

• Size of an array is pre-determined.
• Example
• int number new int5
• Problems
• What if we have more than pre-determined size of
  an array?
• Underutilization of space.

40
Variable-size array declaration

• In Java, we can declare an array of different
  size every time we run a program
• Example
• int size
• int number
• inputStr JOptionPane.showInputDialog(null,"Plea
  se enter the number of elements ")
• size Integer.parseInt(inputStr)
• number new intsize

41
On the fly review

• Given a one dimensional array myArray, what is
  the correct way of getting the number of elements
  in this array.
• a. myArray.length
• b. myArray.length - 1
• c. myArray.size
• d. myArray.size 1

42
On the fly review

• Given a one dimensional array myArray, what is
  the correct way of getting the number of elements
  in this array.
• a. myArray.length
• b. myArray.length - 1
• c. myArray.size
• d. myArray.size 1

43
On the fly review

• Array is a collection of data values of the
  different data types
• a. True
• b. False

44
Arrays for Objects
// An array for the names of the distinct
private Loan loanArray new Loan5

• Note No Loan objects are created. Only a
  container for Loan.
• Each location is initialized to null.

loanArray
NULL
45
Arrays of Objects

• private Loan loanArray new Loan5
• for (i0 ilt5 i)
• loanArrayi new Loan()

loanArray
46
Indexing an Array

• int number new int 5
• number0 2
• number13
• number24
• number3 6
• number4-1

47
Initializing Arrays
... // Differentially number the
assignments. private int number 1, 2, 1,
5, 1, private final int totalNumber
number.length

• No new required.
• Terminating semicolon.
• Optional final comma.

48
Further Initializer Examples
String suitNames "Spades", "Hearts",
"Diamonds", "Clubs" Point vertices
new Point(0,0), new Point(0,1), new
Point(1,1), new Point(1,0), YearlyRainfall
y2k new YearlyRainfall( new
int10,10,8,8,6,4,4,0,4,4,7,10,)
49
Passing Array to Methods

• When an array is passed to a method, only its
  reference is passed. A copy of the array is not
  created in the method.
• That means
• we pass the identifier for that array which in
  fact is a reference to a start address of the
  array.

50
Passing Array to Methods

• Assuming changeArrayValue is one method of a
  class named ArrayClass
• public void changeArrayValue(int arrayChanged)
  
• for (int i0 ilt arrayChanged.length-1 i)
• arrayChangedi 1
• We call this method as

51
Passing Array to Methods

• ArrayClass anObj new ArrayClass()
• int number5 new int5
• for(int i0 iltnumber.length i)
• number0 i
• anObj.changeArrayValue(number)

52
Passing Array to Methods

• for(int i0 iltnumber.length i)
• number0 i
• anObj.changeArrayValue(number)

number
number
53
On the fly review

• The amount of memory allocated to store an array
  depends on
• a. the name of the array
• b. the size of the array
• c. the size and type of values in the array
• d. none of the above

54
On the fly review

• The amount of memory allocated to store an array
  depends on
• a. the name of the array
• b. the size of the array
• c. the size and type of values in the array
• d. none of the above

55
On the fly review

• Arrays are
• a. variable-length entities.
• b. fixed-length entities.
• c. data structures that contain up to 10 related
  data items.
• d. used to draw a sequence of lines, or rays.

56
On the fly review

• Arrays are
• a. variable-length entities.
• b. fixed-length entities.
• c. data structures that contain up to 10 related
  data items.
• d. used to draw a sequence of lines, or rays.

57
The Arrays Class

• Defined in the java.util package.
• Contains static methods for manipulating arrays
• binarySearch search for a value.
• equals compare the contents of two arrays.
• fill fill an array with a particular value.
• sort sort the contents of an array.

58
Multi-Dimensional Arrays

• Arrays of multiple dimensions are possible.
• 2D grid, for a board game such as chess.
• 3D cube structure, etc.
• Multi-dimensional arrays are regarded as being
  arrays of arrays.
• Non-rectangular structures are possible.

59
2D Array Construction
final int numRows 10, numCols 5 double
matrix new doublenumRowsnumCols char
hiddenWord 'd', 'g', 'i', 'b' ,
'e', 'i', 'u', 'm' , 't', 'a', 's', 'a'
,
60
Review

• Arrays make it possible to group related items in
  a single object.
• An array's length is fixed on construction.
• Arrays may have multiple dimensions.

61
Multidimensional Arrays

• Multidimensional arrays
• Tables with rows and columns
• Two-dimensional array
• m-by-n array

62
Two-dimensional array with three rows and four
columns.
63
Multidimensional Arrays (Cont.)

• Arrays of one-dimensional array
• Declaring two-dimensional array b22
• int b 1, 2 , 3, 4
• 1 and 2 initialize b00 and b01
• 3 and 4 initialize b10 and b11
• int b 1, 2 , 3, 4, 5
• row 0 contains elements 1 and 2
• row 1 contains elements 3, 4 and 5

64
Multidimensional Arrays (Cont.)

• Two-dimensional arrays with rows of different
  lengths
• Lengths of rows in array are not required to be
  the same
• E.g., int b 1, 2 , 3, 4, 5

65
Multidimensional Arrays (Cont.)

• Creating two-dimensional arrays with
  array-creation expressions
• Can be created dynamically
• 3-by-4 array
• int b b new int 3 4
• Rows can have different number of columns
• int b
• b new int 2 // create 2 rows b 0
  new int 5 // create 5 columns for row 0
  b 1 new int 3 // create 3 columns for
  row 1

66
Multidimensional Arrays (Cont.)

• Common multidimensional-array manipulations
  performed with for statements
• Many common array manipulations use for
  statements
• E.g.,
• for ( int column 0 column lt a 2 .length
  column ) a 2 column 0

67
On the fly review

• In array items, which expression below retrieve
  the value at row 3 and column 5?
• a. items 2 . 4
• b. items 2 4
• c. items 2 4
• d. items 2, 4

68
On the fly review

• In array items, which expression below retrieve
  the value at row 3 and column 5?
• a. items 2 . 4
• b. items 2 4
• c. items 2 4
• d. items 2, 4

69
On the fly review

• An array with m rows and n columns is NOT
• A. An m-by-n array. B. An n-by-m array.
• C. A two-dimensional array.
• 1. A and C.
• 2. A.
• 3. B.
• 4. C.

70
On the fly review

• An array with m rows and n columns is NOT
• A. An m-by-n array. B. An n-by-m array.
• C. A two-dimensional array.
• 1. A and C.
• 2. A.
• 3. B.
• 4. C.