Can IDEs Do More to Improve Code Quality?

Key idea

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.

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