September 23, 2018
Hot Topics:

Can IDEs Do More to Improve Code Quality? Part II

  • April 28, 2004
  • By Charles-Philip Bentley and Baudouin Le Charlier
  • Send Email »
  • More Articles »

Three possibilities are possible to make this kind of tool a reality:

  • As an Eclipse plug-in (most likely).
  • Integration of the feature in the current Java Development Tool plug-in
  • Incorporation of those checks in the compiler used by Eclipse (less likely)
Key point: By having a well defined environment for documentation and comments, the IDE leverages the documentation and improves the developer's experience.

Synchronization Between Class Comments and Sub Class Comments

The case of the Liskov Substitution Principle

When one is sub typing by implementing an interface or extending an existing class, it is a good practice to follow the Liskov Substitution Principle.

Barbara Liskov first wrote it as follows:

If for each object o1 of type S there is an object o2 of type T such that for all programs P defined in terms of T, the behavior of P is unchanged when o1 is substituted for o2 then S is a subtype of T.

Stated more simply, programs using references to base types must be able to use references to derived types without knowing the difference.

In Java, this principle fits especially well when one is using the pre-conditions and post-conditions constructs that were introduced in the previous section. In this paradigm, the principle easily translates into:

On a synchronized method specification, one may

  • remove one or several pre-conditions
    • The method does not rely on those pre-conditions to successful return.
  • add one or several post-conditions
    • The method is giving more when it returns

Let's show an illustration of the rule of thumb by taking back the method definition of the IWeighable interface; pre-conditions and post-conditions have been integrated.

/**Returns the weight of this object when empty
 * @pre unit != null
 * @param unit the unit to use for the weight
 * @return w = the weight value of the object in the units defined by unit.
 * @post w >= 0
 * @throws WeightException when at least one of the contained objects 
 * does not implement IWeighable
public int getWeight(IUnit unit) throws WeightException;

From the viewpoint of the person who implements this interface, the comment cannot be changed in IWeighable.java. Let's synchronize the Javadoc comment and see what can be changed in Car.java;

/**Returns the weight of this object when empty
 * @pre unit != null
 * @param unit the unit to use for the weight
 * @return w = the weight value of the object in the units defined by unit.
 * @post w >= 0
 * @throws WeightException when at least one of the contained objects
 * does not implement IWeighable
public int getWeight(IUnit unit) throws WeightException {

After implementing the method, the developer might then strengthen the post-conditions by adding @post w >= 1, because any instance of his Car implementation always carries a weight above zero. From the IWeighable perspective, this new post-condition does not change the contract. The LSP is respected. Indeed, when w >= 1, one also has w >= 0.

Is it be possible to remove the pre-condition @pre unit != null? The answer is no. Without this condition, one cannot fulfill the contract defined in the @return tag that states the returned value must be expressed in the units defined by the variable unit parameter. Not respecting such constraint is the kind of mistake that leads Mars probes to crash unexpectedly.

What about exceptions and rules one shall follow? Based on the getWeight definition in the IWeighable interface, for an implementation of getWeight in Java, one

  • Cannot add any throws CheckedException clause.
  • Can remove the throws WeightException clause if the implementation finds a way not to throw any instance without breaking the contract of specification.
  • Can add one or several throws UncheckedException clauses (an unchecked exception is any exception sub classing the RunTimeException class).

Clearly, when one is modifying a Javadoc comment according to the LSP, one needs the whole specification under his eyes to avoid mistakes. A complete Javadoc comment synchronization tool is thus needed, a tool that would help the developer at enforcing the LSP. Such a tool does not yet exist for the Eclipse IDE, but can be expected in the future as a plug-in.

Re-synchronization upon API changes

Changes in interface specifications are rare. However, when changes do happen, one is supposed to iterate through all interface implementations to check the compliance with the new specifications, and make modifications if necessary. This process is not necessary if the specification is changed in such a way as to make it more general. One makes a specification more general by adding a pre-condition or removing a post-condition.

In the current state of affairs, Eclipse does nothing when one modifies the Javadoc comment in an interface. Automatically generating todo tasks is a useful improvement to ease the maintenance work. Such a task may include information such as the modification date and the interface in which the modification was made.

Page 3 of 4

Comment and Contribute


(Maximum characters: 1200). You have characters left.



Enterprise Development Update

Don't miss an article. Subscribe to our newsletter below.

By submitting your information, you agree that developer.com may send you developer offers via email, phone and text message, as well as email offers about other products and services that developer believes may be of interest to you. developer will process your information in accordance with the Quinstreet Privacy Policy.


Thanks for your registration, follow us on our social networks to keep up-to-date