Documentation in Java

Documentation may be divided into two types -- documentation of a program interface and documentation of its implementation. Documentation of an interface is intended to present the information that a user of a program needs to know, while documentation of an implementation is intended to present information to anyone wanting to modify the program, or simply wanting to understand how it works. Here the word interface is used in its ordinary English sense, and not necessarily in the sense of the Java keyword.

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. For one thing, it is fairly common for the implementation of a program to change while the interface remains the same. This means that exposure to documentation of the implementation can be not just confusing but actually dangerous, since it can lure users into relying on implementation details that may change. So for example, if you decide to use program A as part of your program B, and if you 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.

So it's useful if a programming language provides a mechanism for making interface documentation available to a user, while restricting implementation documentation to the source code listing. In Java, the javadoc documentation facility has been provided to do this. You are to use it in your assignments to document your interface. For documentation of an implementation, you should use the // or /* ... */ syntax in addition to javadoc. 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. Another important use for non-javadoc comments is to document design decisions that are made (e.g., the choice of one data type over another).

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 message

Documentation that extends over several lines can be 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.

Documentation in particular CS courses -- J. Smith

Be familiar with the documentation requirements of the department's Java coding style guidelines. But do not interpret their silence about documenting of implementations as saying that such documentation is unimportant.

In particular, you should have javadoc documentation for each public class and method. If you do this for the public methods for a class, then you needn't list these methods as part of your class documentation. Otherwise your class documentation should have such a list.

For programs of the sort assigned in upper-division classes, I am interested in the implementation details and in how much you have thought about them. Therefore you should document implementations as well as interfaces. In lower-division classes, the implementation can often be determined from the interface, so that documentation of the implementation is less important. However, even in lower-division classes you should document at least your instance variables and local variables, since understanding these is usually very helpful in understanding an implementation. In fact, in order to better understand your implementation, I prefer that you have these variables appear at the beginning of the class despite the department guidelines. Recall that these variables will normally be private.

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

  1. Any quirks of your printer, typos in interactive input, etc.
  2. Extra work done for extra credit
  3. Reminders of special arrangements (e.g. an extended due date due to illness)
  4. Differences between the current version and earlier versions of an assignment.