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).
- Unzip StudentGradeExercise.zip archive somewhere on your computer.
- In Eclipse, go to File > Import
- Select General > Existing Projects into Workspace
- At the top where it says "Select root directory", click Browse and choose the location you unzipped the folder to.
- If you don't see anything under "Projects:", you can try selecting the "Search for nested projects" checkbox.
- Select the "Copy projects into workspace" checkbox.
- 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().