This two-part article looks at code quality through the prism of static documentation in the source code. In this first installment, we introduce the important concepts and examine IDE tools for the creation of documentation. Next week, we will talk about the maintenance of existing comments and their uses. We will finish by looking at how the IDE can solve some code convention issues.
The article focuses on the concepts while using Eclipse M8 and the Java language 1.4 to exemplify those concepts. We chose Eclipse because it is becoming an industry standard among third-party tools’ developers. Eclipse is:
- A free and open source universal platform
- Easy to embrace, extend, and use
- Supported by over 50 member companies such as IBM, Intel, HP, and Ericsson
Nonetheless, the concepts described in this article apply to all IDEs. For the sake of completeness, we provide a list of well-known IDEs in the Resources section.
This article is intended for a broad audience. This text hopes to show developers how the IDE can make code comments more attractive. We only assume readers are familiar with OOP programming concepts and the Java programming language.
Some Background Information about Comments
Before continuing on, the reader must be aware that due to well-known limitations put forward by the mathematical theory of computability, it is impossible for a program to verify whether a method is correct.
Key concept
One says a comment is correct when it faithfully describes the behavior of the commented element.
As a corollary, a tool that automatically writes complete and correct comments for the programmer is impossible. However, one can imagine an AI system working informally, like our brain. With its own language, it would be able to approximate the specification of a method. But indeed, that’s for the future. Today, we nonetheless have some pretty neat things that are going to help us in our quest for quality coupled with productivity. This article points out what already exists in Eclipse and what is possible to improve, because indeed there is room for improvements. One should keep in mind that an IDE stuffed with features means an increased learning curve.
In most source code repositories, code comments are rarely seen. There are several reasons for this state of affairs:
- It takes time to write comments.
- Comments have to be maintained.
- Mediocre ergonomics of tools.
Hopefully, IDEs are improving in all those aspects.
Good comments increase code quality. They force the programmer to pay careful attention to the code. For those few able to understand a code base without comments, ignoring them is always an option. However, in a recent Internet survey (see the References section), over half of the respondents said comments do increase the quality of their work, even for small projects. Tools are definitely needed with the implicit issues of usability and productivity.
In this article, we refer to comments as any kind of Java comment in the source code and to Javadoc comments as the specific documentation written for the Javadoc tool. The Javadoc tool is the program that parses Javadoc comments and creates HTML documentation called Javadoc.
Tools for the Creation of Comments
We are first going to look at Javadoc comment creation with the help of an example. Let’s examine the following IWeighable interface that defines the following method:
/**Returns the weight of this this object when empty * @param unit the unit to use for the weight * @return * w = the weight value of the object in the units defined by unit. * w >= 0 * @throws WeightException * when at least one of the contained objects does not implement * IWeighable */
public intgetWeight
(IUnit unit)
throws
WeighException;
This interface is given as such. One is asked to make the Car class implement this IWeighable interface. After grasping the problem at hand by carefully reading the IWeighable specification, one may start writing code for the implementation of IWeighable. One thus states that Car now implements IWeighable. Eclipse then complains by reporting that the Car class should implements the methods defined by the IWeighable interface. The IDE does this inside the editor by underlying in red the “Car” string.
Key notion
The Car class has to be synchronized with the IWeighable interface.
In Eclipse, the “Quick Fix” command is one way to achieve synchronization. The “Quick Fix” pop up window appears when the insertion point is on a problem and one presses Ctrl+1. Synchronization creates method stubs in the Car class.
Does synchronization include Javadoc comments?
In Eclipse, method stubs include a generated Javadoc comment defined by a template.
/**
* ${see_to_overridden}
*/
One will have something that looks like this
/**
* @see IWeighable#getWeight(IUnit)
*/
public intgetWeight
(IUnit unit)
throws
WeighException {
}
Basically, the @see tag provides a link to the getWeight method in the IWeighable interface. Special synchronization is needed when one is using Liskov’s Substitution Principle, which provides a guideline to sub-typing any existing type. For people using this principle, a more complete Javadoc comment synchronization mechanism is desirable. This issue is further discussed in Part II.
Poor visibility of the method specification is clearly a disadvantage of the solution mentioned above. Indeed, for looking up the method specification, one has to:
- Navigate in the IDE to the Javadoc comment in IWeighable.java.
- Look up in a browser the Javadoc of IWeighable.java, which is generated by the Javadoc tool.
- Look up in a browser the Javadoc of Car.java, indeed because the last version of the Javadoc tool synchronizes the Javadoc of interfaces with their implementing classes.
- Use a built-in mechanism in the IDE to display the Javadoc comment from IWeighable.java.
Private methods for the implementation of getWeight
Methods should not be written as big monolithic blocks. Such implementations create duplicated code, decreasing visibility and increasing maintenance work. The performance argument against this breakdown of blocks into smaller ones does not hold. Indeed, optimization techniques such as method in lining are already implemented by dedicated tools. It is generally agreed that subdividing blocks into smaller logical blocks is a good practice. Going back to the Car example, one could create a private method to implement the getWeight method.
private intcomputePassengersWeigh
(IUnit unit)
throws
WeighException {
int
weight = 0; //code
return
weight; }
One notices the importance of writing self-documenting code. So, once a good method name is found, one will start writing Java code. In the heat of the action, the programmer knows what the method is supposed to do. He has a mental image of the method specification. He is therefore tempted to continue on coding. But that wouldn’t be a good thing, neither for him nor for others, mainly because of the two following arguments:
- Maintenance
- Code re-use
These are indeed good arguments for commenting private and package methods.
Putting this last sentence in perspective, one advocates that when a method, a field, or a class is part of an API (Application Programming Interface), it means one has to take extra care to make sure it will be understandable by the broadest audience. For the record, in Java API, members are either declared public or protected.
Eventually, one has to choose the methodology (i.e. the set of procedures one decided to follow for successfully completing a project) that best fits one’s goal. If one is writing a small program once, commenting private members is a bit far off. Furthermore, if the program is not supposed to be released as an API, one could decide not to write any comment at all.
In this article, we hypothesize that Javadoc comments are required. This brings us to the next section.
The Javadoc comment skeleton
The skeleton is sometimes referred to as a Javadoc comment stub. The skeleton word conveys an interesting metaphor as well. While one is programming, one does not like doing repetitive and boring tasks. One wants to use creativity.
Key Definition
The skeleton is all the information the IDE is able to learn by itself about the object being commented (method, field, or class).
Once the skeleton is built, one still needs to flesh out the comment by hand.
/** * @param unit * @return * @throws WeightException */
private intcomputePassengersWeight
(IUnit unit)
throws
WeightException {
int
w = 0; //code
return
w; }
With a single command, all the automatic work is done. This feature deals with the formatting work introduced by the Javadoc language, which is time-consuming work when done manually.
This is a great feature to use. However, the user does not have much control over the stub formatting and its content. One cannot tell Eclipse to include custom Javadoc tags, for example.
The command generating skeletons and Ergonomics concerns
In Eclipse, this command is available while a Java file is open and the insertion point is on a class name, field, or method. This enables the action at “Source à Add Javadoc Comment.” When this command is relevant, it appears in the “Quick Fix” pop-up window.
Any command can be executed slightly faster with a keyboard shortcut. The Eclipse platform lets you customize the keyboard shortcuts for any menus entries, so the obvious solution is to configure the shortcut for the “Add Javadoc Comment” action. You do this by going in “Window -> Preferences; Workbench -> Keys. Now, select the Source command category; this enables you to add or remove key bindings to any menu entry of the Source menu.
Going further on the issue of ergonomics, why should one even use keyboard shortcuts? The IDE should be smart and do that automatically. This concept is already implemented for compilation commands in Eclipse. Indeed, one does not need to manually compile files. How much time does one lose having to manually ask the IDE to compile source files? This is an open question for the reader to answer truthfully.
Key notion
Because the point of using an IDE is to be more productive, the IDE should automatize as many commands’ executions as possible.
To be really useful and adaptive, this concept should insert itself in a broader vision: The best IDE supports a team’s methodology while minimizing the time taken for sticking to the rules. The IDE is a tool automating all tasks required by a methodology and reports infractions. As a consequence of implementing checkable aspects of one’s methodology, the IDE not only increases code quality from a documentation perspective but also the quality of the whole project increases as well.
Key idea
The IDE becomes supportive of one’s methodology.
If a team’s methodology requires Javadoc comments, the IDE seamlessly enforces this requirement by providing tools for working with Javadoc comments.
Fleshing out correct comments
Key Concept
Incorrect Javadoc comments are leading to insidious bugs.
It is critically important to write correct Javadoc comments. They act as contracts that allow clients to use your methods and classes without the need to dig into the code to understand how it works. In that respect, the current technology does not help create correct content. However, IDEs do provide helping features for managing the creation of content.
Eclipse provides a text completion feature inside Javadoc comments. The feature is requested by a CTRL+SPACE key binding. In Eclipse, the completion works for Javadoc tags and HTML tags. This feature does not insert itself into a WYSYWIG tool. No such integration has yet been seen, even though such a tool can greatly increase quality of the Javadoc comments because:
- One would have real-time feedback. For Java, the IDE needs to emulate the Javadoc tool.
- Most importantly, such a WYSIWIG tool can facilitate the link between the implementation phases with previous phases of one’s methodology. One could start using media content such as images (UML charts) inside Javadoc comments.
- Last, the use of a spell checker with an extensible dictionary makes sure comments are meaningful. Eclipse will have a spell check tool for the 3.0 release. However, a WYSYWIG comment editor is not yet on schedule.
The reader now gets an idea where IDEs are headed. The IDE can be thought of as a platform for handling a team’s methodology from A to Z. The IDE is not only a tool for writing Java code. Every component of a methodology is important for achieving great quality. As a side note, another clue of this trend is the wide-spread use of JUnit tests inside IDEs. This enables Test Driven Development methodologies.
As a result, IDEs have to support custom Javadoc tags. Custom Javadoc tags allow extending the language of the Javadoc to fit one’s needs. They allow better control by linking the coding phase with other phases of a methodology. Eclipse does not yet support custom Javadoc tags.
End of Part I
In this part, the subject of the comment creation issue has been introduced. In the background, we have seen that code documentation inserts itself in a more global challenge: supporting methodologies seamlessly. In the next part, we will talk about the maintenance of existing comments and some of their uses. We will finish by looking at how the IDE can solve some code convention issues. A more complete conclusion will be provided as well.
References
B. Le Charlier and P. Flener. “Specifications are necessarily informal,” or: “Some more myths of formal methods.” Journal of Systems and Software, Special Issue on Formal Methods Technology Transfer 40(3):275-296, March 1998. http://user.it.uu.se/~pierref/publications.html
Barbara Liskov and John Guttag. Program Development in Java: Abstraction, Specification, and OO Design. Addison-Wesley Pub Co 2000. ISBN: 0201657686
Eclipse Platform Technical Overview: http://www.eclipse.org/whitepapers/eclipse-overview.pdf
Internet Survey: Code Comments vs You and your IDE: http://forward.at/survey
Resources
CodeGuide: http://www.omnicore.com/index.htm
Borland JBuilder: http://www.embarcadero.com/products/jbuilder
Eclipse: http://www.eclipse.com
Net Beans: http://www.netbeans.org/
MS Visual Studio: http://msdn.microsoft.com/vstudio/
IntelliJ IDEA: http://www.jetbrains.com/idea/
Oracle JDeveloper: http://otn.oracle.com/products/jdev/index.html
About the Authors
Charles-Philip Bentley is a computer science engineering student at the Catholic University of Louvain (UCL). He is currently writing his “mémoire” titled “Research on tools for code specification and commenting.” His main interests are OOP methodologies, user interface ergonomics, and software engineering techniques.
cbentley@student.info.ucl.ac.be
Baudouin Le Charlier is a professor at the Catholic University of Louvain (UCL). His research interest includes program analysis by abstract interpretation, program verification, intrusion detection, and the interoperability of programming languages. He teaches programming methodology, programming languages concepts, and formal syntax theory.
blc@info.ucl.ac.be
