March 1, 2021
Hot Topics:

Can IDEs Do More to Improve Code Quality?

  • By Charles-Philip Bentley and Baudouin Le Charlier
  • Send Email »
  • More Articles »

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) 



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) 


 WeighException {

Page 1 of 3

This article was originally published on April 20, 2004

Enterprise Development Update

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

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