6.16. Documentation¶
Whew! This was such a long chapter. Who knew that methods would be so complex? But good news! We are almost done with our discussion of methods. We just need to talk about one more thing.
Whether you are coding for the AP exam or the amazing careers you will all have after you graduate, you will encounter something all programmers call software documentation. Documentation is written text that aides the development and maintenance of a program. It is especially useful when a program must be improved upon by other developers because it can more efficiently transfer contextual understanding to developers that were not present when the program was originally developed. In other words, documentation is the English you will write in your programs to help you and others understand what the hell you were thinking when you created a program.
Documentation will look different for each programming language that you know, but because this course is all about Java, we gotta talk about how to document Java programs. The documentation that we write and read in this class will always follow patterns like this:
// This is a single line comment
/*
* This is a multi-line comment
*/
/**
* This is JavaDoc
*/
Does some of this look familiar to you? If it does, you’re totally right! We have seen multi-line comments in our repl.it assignments before. Throw in a lot more asterisks and you have created a style of comment that will make any Java programmer proud.
More specifically, we include documentation for every major component of our Java classes. This includes documenting our method definitions, as well as any other parts of our classes that might need a little more clarification. Got a confusing looking instance variable? Throw in a single line comment. Does your constructor do something weird? Again, document that code! Most programmers would rather have you include way too much documentation than too little, so if you’re ever unsure, just start writing.
I want to focus on the last comment style, JavaDoc, because this will be on the exam. JavaDoc comments are often used to document method definitions, like so:
/** The onLine method determines if a Point can be found on a Line.
* This is one possible solution to the extra credit portion of our repl.it assignment titled "Constructors and Parameters".
* @param p a Point object that consists of an x and y coordinate
* @return true if the Point can be found on a Line generated by two other Point objects.
*/
public boolean onLine(Point p){
double b = this.getYIntercept();
double m = this.getSlope();
return (p.getY() == ((m * p.getX()) + b));
}
Typically, we use the first part of the JavaDoc comment block to describe what the method does. You can also include any other information that you think might be helpful for other programmers to know. In the example above, I included a sentence about our repl.it assignment because I know a little bit about the programmers who are going to read this comment block – you!
After your description of the method, you will want to use @param to boldly describe a method’s parameters, if it uses them. If there are no parameters found within the method definition, then you don’t have to worry about using @param.
You will also want to use @return for any method that returns a value. This should be used to highlight what values are returned as well as the conditions that produce said values. In the example above, the method can return either true or false. We want to make sure that we say “This method returns true” but we also want to say when it returns true. In the example above, the method returns true if a point can be found on a line.
Want to see an example of documentation that you will see on the exam? Take a look at this ScoreInfo class found on last year’s exam:
class ScoreInfo{
int score;
int numStudents;
public ScoreInfo(int aScore){
score = aScore;
numStudents = 1;
}
/* adds 1 to the number of students who earned this score
*/
public void increment(){
numStudents++; //This is equivalent to numStudents = numStudents + 1;
}
/** @return this score
*/
public int getScore(){
return score;
}
/** @return the number of students who earned this score
*/
public int getFrequency(){
return numStudents;
}
}
The documentation on the AP exam will normally look a lot more complex than what you see above. We will continue to add to our understanding of how to write and understand JavaDoc comments as we continue to learn more about how to program in Java. For now, practice looking for and writing comments that use @param and @return.