March 9, 2021
Hot Topics:

Can IDEs Do More to Improve Code Quality? Part II

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

In our previous article, we looked at IDE tools for the creation of documentation in the source code. This time, we are going to talk about comment maintenance, among which synchronization and code conventions are major issues. Then, we introduce some custom Javadoc tags and their uses. Finally, we look at miscellaneous uses of comments.

Comment Maintenance

In this section, we discuss aspects and tools that ease the task of working with an existing code base.

We are first going to define an important term that will be used throughout this part.

Refactoring is the part of code maintenance that doesn't fix bugs or add new functionality. Rather, it is designed to improve the understandability of the code or change its structure and design, to make it easier for human maintenance in the future.

Code Convention

Code conventions are non-absolute rules defined by a group of people. The objective of those rules is to reduce confusion among the group. One can distinguish naming conventions and formatting conventions.

Formatting conventions

A good IDE removes formatting from the programmer's responsibility. Ideally, one wants incremental formatting when saving a source file. Except from defining the format to use, the programmer is not distracted by the job of formatting and can focus on writing code.

In Eclipse, one has to format the source code manually by executing the "Source Format" action. This formats the source code according to format preferences. One can find them in "Window -> Preferences; Java -> Code Style -> Code Formatter." In the Code Formatter, one can define a wealth of variables, from lines breaks to braces positions.

Formatting conventions are a very small part of a bigger picture. Indeed, one can glimpse the pattern that was already introduced in Part I: The IDE now supports the developer by implementing checkable aspects of his methodology.

Naming conventions

In Eclipse, the developer can define prefixes and suffixes for the following variable types:

  • Fields
  • Static fields
  • Parameters
  • Local variables

For example, there is a growing trend in the Java community to prefix private fields with an underscore.

private String _ownerName;

One also usually declares constants with capital letters:

public static final int LIGHT_SPEED = ...;

The aim is to increase code readability. Eclipse does not fully implement this aspect. Indeed, Eclipse only uses the above prefixes and suffixes for generated code. Eclipse does not generate a warning for source code that doesn't comply with the prefix convention. However, plug-ins such as "Checkstyle" (see the Resources section) exist to enforce such naming conventions.

Naming methods and variable identifiers

For methods, by looking at the name, one should guess what the method is supposed to do. It is important to strike a balance between conciseness and strength of meaning.

Key Concept: Names should be self-documenting.

For variable identifiers, the previous argument applies as well. However, it is quite handy to use short variable names. Indeed, many people find such code easier to read. But, other people like longer names better, so how does one solve this dilemma?

One solution lies in renaming variables on the fly when needed. However, this is only imaginable for closed-world variables, variables whose uses are all known to the IDE. Thus, based on meta-data indicating how to construct an identifier, the IDE refactors the code on the fly for the following:

  • Private fields
  • Local variables
  • Parameters

One could possibly do that for package identifiers as well. However, for big packages the operation becomes time consuming.

Protected and public are API variables (i.e. open-world variables). Renaming such variables constitutes an API change and so potentially breaks client code.

Synchronization Between Code and Comments

Once comments are written, one wants them to stay synchronized with the code. In other words, when a change is made in the source code, the comments must be updated accordingly. When a comment is not synchronized, it loses its meaning.

//Comment explaining why D is used
int result = D*F+G;

If someone decides to change the name D to R without updating the comment, it becomes hard to use. Occurrences of D in the comment might point either to F, G, or the new R.

Remark: Broadly speaking, when redundant information is present, synchronization becomes difficult if the system has to stay coherent.

Page 1 of 4

This article was originally published on April 28, 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