Can IDEs Do More to Improve Code Quality?
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.
weight = 0; //code
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:
- 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.
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 */
w = 0; //code
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.
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.
Page 2 of 3