|
Documentation_Standards
Documents the standards and conventions for code comments.
Substantial portions of this document are taken directly from the Ptolemy II project documentation (Volume 1: Introduction to Ptolemy II). The source code documentation in the Ptolemy II project is exemplary, and should serve as a baseline from which to judge the quality of our own comments. IntroductionGood comments are essential to easily readable and maintainable code. Good comments actually extend the life of code because well-commented code is more likely to be reused rather than rewritten. For open source projects, well-documented code communicates to casual observers and potential contributors that the project is committed to producing mature, quality code. It is critical that documentation be written at the time of development when details are still fresh in your mind, rather than six months later as an afterthought. Likewise, when code is modified and/or extended, the comments and other documentation about the code should be immediately updated to reflect the changes. Code comments fall into two categories:
All Javadoc and code comments should be complete thoughts, capitalized at the beginning and with a period at the end. Spelling and grammar should be correct. JavadocJavadoc is a program distributed with the Java SDK that generates HTML documentation files from Java source code files. Javadoc comments begin with /** and end with */. The comment immediately preceding a code construct (method, member, or class) documents that code construct. Javadoc documentation should be provided for all projects, packages, classes, interfaces, enums and all public, protected, and private members and methods contained therein. Please take the time to familiarize yourself with the finer points of Javadoc at this URL: http://java.sun.com/javase/6/docs/technotes/guides/javadoc/index.html. When writing Javadoc comments, pay special attention to the first sentence of each Javadoc comment. This first sentence is used as a summary in the Javadocs. It is extremely helpful if the first sentence is a cogent and complete summary. Javadoc comments can include embedded HTML formatting. Please use HTML comments sparingly, and make sure the markup is well-formed. Any code included in comments should be wrapped in code tags: <code>i = 1</code>. The Javadoc program gives extensive diagnostics when run on a source file. Comments should be formatted until there are no Javadoc warnings. Class DocumentationThe class documentation is the Javadoc comment that immediately precedes the class definition line. It is a particularly important part of the documentation. It should describe what the class does and how it is intended to be used. When writing it, put yourself in the mind of the user of your class. What does that person need to know to clearly understand what the class is for? A clear explanation is especially important when a person doesn't have a clear understanding of the larger system. Usually, it is of little help to explain implementation details of the class. A class may be intended to be a base class that is extended by other programmers. In this case, there may be two distinct sections to the class documentation. The first section should describe how a user of the class should use the class. The second section should describe how a programmer can meaningfully extend the class. Only the second section should reference protected members or methods. The first section has no use for them. Of course, if the class is abstract, it cannot be used directly and the first section can be omitted. Each class comment should also include the following Javadoc tags:
Constructor DocumentationConstructor documentation usually begins with the phrase "Constructs an instance that ..." and goes on to give the properties of that instance. As with class documentation, it is important to communicate the specifics of the constructor behavior in the first sentence as this is the one that will show up in method summary. Method DocumentationMethod documentation needs to state what the method does and how it should be used. It is almost never useful to simply provide an English translation of the code. This is a good example of the type of method documentation that is expected: /**
* Marks this object invalid, indicating that when a method
* is next called to get information from the object, that
* information needs to be reconstructed from the database.
*/
public void invalidate() {
valid = false;
}By contrast, here is a poor method comment: /**
* Sets the variable valid to false.
*/
public void invalidate() {
valid = false;
}While this certainly describes what the method does from the perspective of the coder, it says nothing useful from the perspective of the user of the class, who cannot see the (presumably private) variable valid nor how that variable is used. On closer examination, this comment describes how the method is accomplishing what it does, but it does not describe what it accomplishes. Here is an even worse method comment: /**
* Invalidates this object.
*/
public void invalidate() {
valid = false;
}This is no more helpful than reading the method name. Comments for base class methods that are intended to be overridden should include information about what the method generally does, plus information that a programmer may need to override it. If the derived class uses the base class method (by calling super.methodName()), but then appends to its behavior, then the documentation in the derived class should describe both what the base class does and what the derived class does. Tags in method documentationAll methods (default, private, protected, public) should include the following Javadoc tags:
Referring to methods in commentsWhen referring to methods and members of the current class, as well as methods and members of outside classes, try to always use the @link tag rather than just using the method or member's name. When done consistently and properly, renaming and refactoring of code is much simpler because Eclipse will automatically change the name of the method or member everywhere it is used with the link tag. Maintenance therefore is automatically performed by the IDE, thus saving a ton of time. For example, a link to a local method would look like: /** Unlike the {@link #foo(String)} method, this method... */A link to an outside method would look like: /** Unlike the {@link org.imirsel.nema.flowservice.FlowService#getJob(long)} method, this method... */Note the octothorpe (# sign) instead of a dot operator between the class and the member. Eclipse provides typing assistance when creating links such as these. Start typing your class name, then type ctrl+space to activate the auto-completion. If there is ambiguity, Eclipse will prompt you to make a selection from a menu of options. Referring to classes in commentsWhen referring to domain objects, entities, and other types of classes in comments, try to always use the @link tag rather than just using the class's name. When done consistently and properly, renaming and refactoring of code is much simpler because Eclipse will automatically change the name of the class everywhere it is used with the link tag. Maintenance therefore is automatically performed by the IDE, thus saving a ton of time. For example: /**
* Kill a running {@link Job}.
*
* @param jobId Unique ID of the {@link Job} to kill.
* @throws IllegalStateException if the {@link Job} is not running.
*/
public void abortJob(long jobId) throws IllegalStateException;Here, Job is an entity. The Job type is not referenced in the method itself, only the Javadoc. But by using the @link tag, if the Job class is renamed to JobDetails for example, all Javadoc references to Job will be updated with the new name. In the above example, assume that the Job type has been imported into the class. Otherwise, the fully qualified name of the class would be required for Javadoc to successfully create the link when the Javadoc was created. |
Thanks Andrew. Anything specific for interfaces and abstract classes while writing javadocs