Tutorial 5 (Feb 2): Classes part 1, Javadoc

Class Example

Download slides summarizing the major concepts and keywords for Classes (PDF revised Feb 6)
     Revision: Fixed a bunch of typos sorry. Also added more to the this keyword to make it more clear.
     Important! I made a mistake on the last slide using this() as a constructor. The correct way is "this(0, 0" and not "this.Point(0, 0)", sorry about that! (Thanks Lisa for catching that.)

Download exercise: StudentGradeExercise.zip
Download instructions (DOCX, PDF).

  1. Unzip StudentGradeExercise.zip archive somewhere on your computer.
  2. In Eclipse, go to File > Import
  3. Select General > Existing Projects into Workspace
  4. At the top where it says "Select root directory", click Browse and choose the location you unzipped the folder to.
  5. If you don't see anything under "Projects:", you can try selecting the "Search for nested projects" checkbox.
  6. Select the "Copy projects into workspace" checkbox.
  7. Click Finish.

There are two classes here:

  • The GradeSimulator class is complete, and will be used to test your Student class.
  • The Student class has documentation only, you need to fill in all the class/instance variables, and class/instance methods, based on the given information.

The documentation has been converted to a Javadoc here.

Further examples:

  • The examples involving DateTime in Chapter 4 of your textbook.
  • This simple game I made, undocumented for now.

Javadoc

In Eclipse, to automatically generate the Javadocs comments, place your cursor on a blank line above your constructor or method. Type "/**" and press <Enter>, it should fill in the rest like this:

/**
 * Student(String, String)
 * This designated constructor sets the first and last name of the student. It
 * also gives the student a unique ID, based on the class variables. 
 * @param firstName First name of the student as a String.
 * @param lastName Last name of the student as a String.
 */
Public Student(String firstName, String lastName){
     this.firstName = firstName;
     this.lastName = lastName;
}

When you have comments formatted like the example above, you can use the javadoc tool to automatically generate Javadoc.

  • Eclipse: Select Project from the top menus, then click "Generate Javadoc..."
  • Terminal/Cmd: Navigate to the folder where your code is stored, then type javadoc -d ./docs * to create Javadoc inside a folder called docs.

Javadoc and commenting code

Javadoc can often be enough to describe what a function/method does. However, never be afraid to add more comments in large blocks of code, or where code is unclear.

Why Object-Oriented Programming (OOP)?

With Object-Oriented Programming (OOP), you can easily and accurately describe the objects around you. For example, I can make a "SmartPhone" class, and define a "SmartPhone" object (an instance of SmartPhone class) called edwinsPhone. The new object can have attributes/properties/variables such as brandName = "Apple", model = "6s", or owner = "Edwin". It can have instance methods like phoneSomeone() or togglePowerButton().