It is important always to document your code clearly. For Java
programmers, some general commenting conventions have been
established by a tool called javadoc, the Java API
documentation generator. This tool can automatically extract
documentation comments from source code and generate HTML class
descriptions, like those in the cs1705
Package API. This tool is so popular and so commonly used that
it has set the standard for how people document the externally visible
features in their Java code.
The javadoc tool expects comments to be written in a particular
way--other comments are ignored. JavaDoc comments (also called just "doc
comments") always start with "/**" and end with
"*/". Any other comments are ignored when generating
documentation for your code. Further, a JavaDoc comment describing something
always appears immediately before the thing it documents.
Within a JavaDoc comment, special tags can be embedded to signal
particular kinds of information. These doc tags enable complete,
well-formatted API documentation to be automatically generated from your
source code. All JavaDoc tags start with an at-sign (@).
If you already know some HTML, you can even embed simple HTML markup inside your JavaDoc comments, and it will appear in the generated documentation for your classes. This is handy if you want to add bullet lists in a class description, or wish to make part of your comment stand out in boldface, and so on.
You should place a descriptive JavaDoc comment just before the start of each class you write:
/**
* Write a one-sentence summary of your robot task class here.
* Follow it with additional details about its purpose, how many
* robots it creates, and how to use it.
*
* @author Stephen Edwards (stedwar2)
* @version 2003.09.10
*/
public class HarvestField
. . .
{
. . .
}
Class descriptions typically use two tags: @author
indicates who wrote the file, and @version indicates
the "version" of this file or project.
You can use your full name, or just PID, in an @author tag.
In this course, it is fine to use the date when the file was
written as the version information in the @version tag.
@author and @version,
make sure to put them at the beginning of the line within the doc
comment.
In lab,
list all lab partners on the @author line. Also, if you
started off with a comment generated by BlueJ (like the example above),
don't forget to replace the text inside the comment with your own.
The javadoc tool will use the very first sentence of your
comment as a one-sentence summary of your class, and will use the entire
text of your comment as the full class description.
Remember that if you just write regular comments, they won't be recognized as "official" descriptive text for document generation:
// This comment describes what this class does, but because it
// uses //, it won't be recognized as a JavaDoc comment.
public class HarvestField
. . .
{
. . .
}
You should place a descriptive JavaDoc comment just before each method or constructor you write:
/**
* Turn right by going 270-degrees left.
*/
public void turnRight()
{
. . .
}
As with other JavaDoc comments, make sure this appears just before the
method it describes. For methods that have parameters, you should also
include a brief description of what each parameter means. For example,
we might have a Harvester robot class that provides its
own constructor:
/**
* Create a new Harvester robot.
* Together, the street and avenue parameters identify the corner
* on which the robot should be created.
*
* @param street create the robot on the given street
* @param avenue create the robot on the given avenue
* @param facing direction in which robot should point
* @param numBeepers number of beepers initially in beeper bag
*/
Harvester( int street,
int avenue,
Direction facing,
int numBeepers )
{
. . .
}
Here, a @param tag has been used to give a description
of the meaning and use of each of the parameters. Be sure to start
these tags at the beginning of a comment line, and group all of the
tags with the same name together (i.e., all @param tags should
be next to each other).
Again, javadoc will take the first sentence in your comment
as a one-sentence summary of what the method does. The remainder of the
comment will be used in generating a full description of the method.
Some methods have return values--that is, they give back information
to their caller. For example, a wallOnRight() predicate
might return a boolean true or false result to indicate whether or not
there is a wall to the Robot's immediate right. You can document what
information is returned using a @return tag:
/**
* Check for a wall to the robot's immediate right.
* Leaves the robot's orientation unchanged, so it will still be
* facing in the same direction.
*
* @return true if there is a wall to the right, or false otherwise
*/
public boolean wallOnRight()
{
. . .
}
Within a BlueJ project, you can use the Tools->Project Documentation command to generate full documentation for your own project straight from your source code. It may take a minute, but once complete, a new browser window will open showing all of the generated documentation for your classes. It will be similar to the cs1705 Package API, but for your own code.
Also, when editing a single file, you will notice a drop-down list on the upper right of the edit window. This list gives you two choices: "Implementation", which shows the code you normally edit, and "Interface", which will instead show the generated documentation view for the current class.
Using these two approaches within BlueJ, you can check out how your comments look in the generated documentation.
JavaDoc comments are "public" documentation of the externally accessible
features of your classes. Often, you may also wish to include
"internal" (that is, private) documentation that is only useful
to someone reading the source code directly. Any comment that does
not begin with /** is treated as private, purely
for someone with access to the source code. You are free to
use such comments where ever you like to improve the readability
of your code, but ...
Choose all names carefully so that a naïve reader's first interpretation will always be right. Do not choose names that might mislead someone about what a method is supposed to do, or what information a variable holds. Choosing poor names or convoluted logic structure and then trying to explain it in lengthy comments does little to improve readability. This is doubly true for methods, because half the time a reader will see your method name where it is called, not when they are reading your method itself. If it is not immediately clear what the method should do, that affects the readability of all the code calling this method, no matter how many comments you put in the method itself.
Strive to write code that is clear and understandable on its own, simply by virtue of the names you have chosen and the structure you use. If you feel you have to add an internal comment to explain something, ask yourself what needs explaining. If you need to explain what a name refers to or how you intend to use it, consider choosing a better name. If you have to explain a complex series of if statements or some other convoluted structure, ask yourself (or a TA) if there is a better way. Only after considering these alternatives should you add descriptive comments.
Consider these comments:
karel = new VPIRobot(); // Create a new robot
x = x + 1; // Add one to x
karel.move(); // move forward one step
These are examples of useless comments. Many students add comments to their code just to "make sure everything is documented", or because they believe copious comments are what the instructor is looking for. Comments like this just get in the way of reading the code, however. You should only add comments when they express something that isn?t already evident from the code itself. Comments are more code that the poor reader has to wade through, so you need to carefully balance their benefits against the cost of having to read them.