Ordinary users of a program do not normally need to know how it works. For these users, documentation of the implementation is generally useless if not confusing. In fact, exposure to documentation of the implementation can be dangerous, since it is fairly common for the implementation of a program to change while the interface remains the same. So if you decide to use program A as part of your program B, and rely on a particular implementation detail of program A, your program B can fail to work if program A is modified to use a different implementation. Keep in mind that one important principle of modern software engineering is that programs should be constructed so that it is easy to modify the implementation while preserving the interface.
The javadoc documentation facility is appropriate for interface documentation, but not for documentation of an implementation. For documentation of an implementation, you should use the // or /* ... */ syntax in addition to javadoc. For the very simplest programs, the implementation can be determined from the interface, so that documentation of the implemenation is not particularly important. However, even for programs of the complexity of those seen in CS 146, it is important to document the interface.
For example, for all but the simplest methods, there is more than one algorithm that can be used. Documentation of the implementation should describe this algorithm, by giving its name if it is a well-known one, and in more detail otherwise. Except for the simplest algorithms, lower level comments are helpful to describe how the instructions or small groups of instructions of the method relate to the overall algorithm. Other important uses for non-javadoc comments are to document design decisions that are made (e.g., the choice of one data type over another), and how errors are handled.
Documentation should be easier to read than the code, and should be in the language of the application. So for example, the short comment in the example below is inappropriate, and should be replaced by a comment that describes what the effect will be of sending the given message to the given object in the particular application.
/*
This is a poor example of documentation --
the documentation isn't any easier to read than the code,
and isn't in the language of the application.
*/
x.update(); // send x the update messageDocumentation that extends over several lines is usually easier to read if you use appropriate indenting. Blank lines between function defintions, and between the documentation and the definition of a function, also help readability.
Be familiar with the department's Java coding style guidelines. But do not interpret their silence about documentating of implementations as saying that such documentation is unimportant.
It is considerably easier to understand the implementation of a class if the interpretations of the instance variables are known. Therefore, despite the department guidelines, I prefer that you have these variables appear at the beginning of the class definition. Recall that these variables will normally be private.
If you use javadoc, you needn't list the public methods of a class.
Local variables are sometimes of sufficient importance to the understanding of a method's algorithm that they should be documented.
If you have a separate test function, you can document it simply by identifying it as such. Normally I will provide such a function, and so you needn't worry about writing or documenting a test function.
You should document any changes in the algorithm, data types, specifications, test program, or programming environment from those assumed in class. Be aware that I may deduct for such changes, so it's usually a good idea to ask whether such a change is acceptable.
Handwritten documentation will earn a small deduction except for your name on the printed output, indication of where the answer appears in the printed output if this isn't otherwise clear, and documentation of