Coffea Works

The Benefits of Coding Standards

Using Enerjy Code Analyzer

by Nigel Cheshire and Richard Sharpe

It is a fact of life -- developers like to write code in different styles. Show us code written by ten different developers and we can show you ten different coding styles. So why should we try to develop and enforce coding standards?

Why Coding Standards?
The primary reason for adopting a set of coding standards is to make it easier for developers to read and understand each other's code. Although peer review is still relatively rare, almost most of us have to maintainor at least step throughcode written by someone else. A lot of time can be wasted just trying to decipher code that is not easy to understand. It is amazing how a few minor style differences can make reading code that much slower.

According to Sun Microsystems, 80% of the lifetime cost of a piece of software goes to maintenance, and hardly any software is maintained for its whole life by its original author.

This is becoming a key issue for many organizations. To get an effective grip on development costs, however, you need to understand the development process, and that means an understanding of the total cost of building and maintaining your software systems.

The adoption of coding standards should not increase costs. All those fancy multi-line comments at the top of files with beautifully lined-up columns of asterisks are a thing of the past. Standards should take care of easy decisions for you, leaving you free to concentrate on the real work.

A second reason for adopting coding standards is to pre-empt bugs as the cost of fixing a bug rises exponentially over time. Finding and fixing bugs in the development phaseand preferably even prior to unit testingcan save hours of time and resources later. Certain coding standards can make it less likely that bugs will be introduced into the code, and if those standards can be applied as the code is written, the savings will be huge.

Another common area for the adoption of a set of standards is on code commenting. A good set of coding standards sets out a common philosophy on this subject. One approach to commenting"the code is the documentation"stems from hard-won experience with trying to maintain heavily commented code in which the comments have fallen out of sync with the code.

Keep in mind that bad or out-of-date comments are worse than useless: they can cause others a great deal of wasted time and frustration. To quote Sun Microsystems: "When you feel compelled to add a comment, consider rewriting the code to make it clearer".

Javadoc is a great tool to adopt for those areas of your code that justify the maintenance overhead of being well-documented, such as APIs. If Javadoc is used, though, it should be used correctly and completely, and standards can and should be applied to its use.

Adoption of coding standards is now more common than ever. Companies expect quality written code as de-facto from their developers and contractors, as it is recognized more and more that others will maintain these applications in the future.

The problem is that one has to be very self-disciplined to remember to apply all of the standards while writing code. You have to learn and memorize them all (Sun Microsystem's coding standards are very concise, but they still run to 20 pages), and then remember to apply them all the time. This can be especially difficult for those who are not used to using standards, or worse, those who are used to a different set of standards. It is not surprising that many coding standards fall into disuse during development, only to have someone rework the code at the end of a project to comply with the customer's standards.

Introducing Enerjy Code Analyzer
Code analysis tools, such as Enerjy Code Analyzer, provide an easy way to check your code against a set of standards as it is being written. This is a significant step forward in promoting the adoption of standards, since it makes it easy for developers to police themselves.

Enerjy Code Analyzer works from within your IDE and the integration is very tight. In particular, aside from setting up the rule-set to be used, there is no need to do any additional configuration after the product has been installed; it reads all the configuration data it needs from the project definition in the IDE.

Code Analyzer applies a pre-configured set of rules to a piece of code and points out any violations of the coding rules. Moreover, for many of the more straightforward rules, Code Analyzer will suggest and apply a fix for you. Alternatively, Code Analyzer can be run over a project or package and report (and fix) violations on previously written code.

Setting the rule set is very easy, simply select/deselect the relevant tick-boxes for each individual rule or group of rules. Since these are maintained within the IDE, there never arises a need to search or edit the configuration files, which would require learning the internal structure of the rule engine to use the tool effectively.

Figure 1: Setting the Ruleset

Some of the rules included are configurable; for example, 'Class name has required form' requires the rule to be configured with the relevant parameters. If your customer states that all classes have to be prefixed with their company name ('Acme_', for example) you can enter this parameter, and all class names will follow that standard, as shown in the following screenshot:

Figure 2: Configuring an Individual Rule

In addition to this, each rule can be prioritized; for example, Javadoc violations can be set as informational warnings (Low priority) while comparison operators (==) used between objects may be prioritized as errors (High priority) due to the fact that although the code will compile this may result in a run-time error.

Figure 3: Prioritization of rules

The set of rules provided with Code Analyzer breaks down into a number of areas:

Standards compliance
correct naming conventions, length of classes, correct use of Javadoc, for example
Unused elements
unused private variables, unused method parameters, for example
Common coding errors
incorrect comparisons, non-terminated cases in switch statements, missing braces, for example
Formatting issues
line length, comment length, for example
EJB
non-public session bean, invalid modifier for entity bean Finder method, for example

While each individual rule can be enabled or disabled in the overall configuration file, you may need to disable a rule for a particular file, or even an individual statement or group of statements. To disable a rule for a whole file, insert a comment before the type declaration that includes a special sequence of characters (ESCA*) and the name of the rule to disable. Multiple rules can be disabled with a single comment by separating the rule names with commas. One or more rules can be disabled for an individual statement by preceding the statement with a different escape sequence (ESCA-) and the name of the rule(s) to be disabled.

Analyzing Your Code
Once the rule set is created, running Code Analyzer is easy. Within your IDE, right click the file name (package or project) and select Enerjy Code Analyzer - Analyze. (Alternatively if you have opted to invoke Code Analyzer on a Save operation, make a change to the source file and save it). Code Analyzer then analyzes your code and the violations appear in the Problems pane.

Figure 4: Running Enerjy Code Analyzer

Click on a violation in the Problems pane to go to the line of code in the main window. Code Analyzer also has a Help functionality (built into the native IDE help system) that provides details on why the violation took place and shows an example of how to code the violating area. The Help system thus serves as a learning tool for beginners as well as a handy reminder for more experienced developers.

Figure 5: Acquiring Help with a Code Violation

Code Analyzer can 'autofix' simple violations (the '@author' tags in Javadoc, for instance) by inserting the correct code in every Java file that needs to be modified. However, serious violations that may need extensive reworking are not auto-fixable. This has been done to prevent Code analyzer from inadvertently altering the functionality of the code. Code Analyzer simply highlights these areas and leaves it to the developer to fix the violation (or leave them as is).

Code Analyzer is not intended to enforce rules. Rather, the aim is to provide a beneficial aid, which will free developers to concentrate on "more complex" issues than the formatting of the code.

Getting the Most from Code Analyzer
The key to successful implementation of the Enerjy Code Analyzer is in defining your rule set. This should be based onand ideally should totally defineyour own set of coding standards. The rules shipped with Enerjy Code Analyzer are built-in from Sun Microsystem's recommended Java sources including The Elements of Java Style from Cambridge University Press (ISBN 0-521-77768-2), Effective Java Programming Language Guide from Addison-Wesley (ISBN 0-201-31005-8), and Java(TM) Language Specification (2nd Edition) from Addison-Wesley (ISBN 0-201-31008-2).

Although a comprehensive rule set is provided with Code Analyzer, you may need to add your own rules to include special standards that are not covered by the standard rule set. New rules can be added by writing new Java classes and integrating them with the analysis and reporting engine of Code Analyzer. The developer can use the API provided by Enerjy Software to interrogate any of the class members (including Javadoc) via an abstract syntax tree, which can be traversed and retraced to determine if a member (or group of members) conforms to a specific rule or algorithm.

Therefore, a thorough review of your coding standards is an important step in the implementation of the Code Analyzer. Although there is much value in simply applying the standard set of rules to your code, it will be more beneficial if you design and review your (or your customer's) rules upfront. Rather than cross check all the standard rules against your coding standards, it is recommended to run Code Analyzer with the standard rules enabled against your existing code base. For each problem that the tool finds, you can either fix the code or disable the rule. Once you have completed this exercise you will see how powerful the tool is, how much time will be saved performing code reviews and, if found, how your code can be checked thoroughly, removing the human factor.

Once a common rule set is decided, all developers can share it through the use of a common configuration file. This file can be exported to the server and imported, as a read-only file, into the developers' IDEs. This ensures that each developer fully complies with the standards set. Once an individual developer has submitted the code for review, the reviewer can run the Code Analyzer report and no rule conflict should be evident. The report can be output as either HTML or XML (XML can be incorporated into your standard reporting tool). Note that the report is automatically created if Code Analyzer is run as part of an ANT batch build.

Figure 6: A Report of Enerjy Code Analyzer

The report should be blank with zero problems found. If any problems are reported, the number of occurrences is shown along with the chosen rule priority and whether or not the rule is auto-fixable. Further detail shows the line number of the violated rule per Java file and any files or packages that have been filtered out of the analysis.

Code Analyzer integrates with all the major IDEs, which makes it very easy to use. The following IDEs are currently supported:

Eclipse Release 2.x or 3.0, from the Eclipse Foundation
JBuilderTM Release 7, 8, 9, X, 2005, from Borland
WebSphere Studio Application Developer Release 5.x, from IBM
Oracle9i JDeveloper Release 9.0.3 or JDeveloper 10g Release 9.0.5.2, from Oracle Corporation
NetBeans Release 3.4.x, 3.5.x or 3.6, from NetBeans.org
SunTM ONE Studio 4 or 5, from Sun Microsystems

The tool can also be used with Apache Ant, binding to its build script. This allows you to run a controlled analysis every night on the whole code base, to ensure that all the code conforms to the standards. It also allows reports to be run for developers who prefer to use a text editor (or an unsupported IDE) for their development needs.

It is quite common for Java development teams to use different IDEs within the same team. In this case, the use of a tool like Code Analyzer can have significant benefits, since it becomes possible to standardize on a set of coding standards that can be applied to each developer, irrespective of the IDE being used.

Keeping It Simple
Coding standards are being adopted by more and more development organizations. Estimates suggest that 80% of the total cost of a piece of software goes into maintenance, and not enough effort is being directed at ensuring that the quality is maintained during the development process. Further, development and Quality Assurance teams are spending too much time in code reviews, correcting coding standards violations that could be detectedand in some cases correctedautomatically.

As we have seen over the course of this article, Enerjy Code Analyzer allows a development team to programmatically define and share a common set of standards, and apply them while they are writing code, irrespective of the development environment they choose. Once a common set of standards has been defined, it can be shared among the development group. For organizations that want to adopt a set of coding standards as well as for those that have a set which needs to reinforced time and again, Enerjy Code Analyzer can make the difference between a set of standards that is never used and one that is built into every line of code that is written.

About Enerjy Software
Our Tools: Enerjy's suite of Java tools strives to provide tactical, comprehensive, andat their heartuseful solutions for the everyday Java developer. Our tools keep you inside your IDE, where you spend eight (ten?) hours a day, and get you back to your curly braces and semicolons, where the work really matters. You'll get simple-to-read tables and easily recognized graphs, and you'll always be a double-click away from your code.
Our Company: You'll find that we're a little different from other software tools companies. Instead of trying to sell you everything, an all-encompassing development solution, we're maniacally focused on giving you just the help you need, when you need it, and then getting out of your way. And we won't charge you an arm and a leg for our tools. We've built the company from the ground up with a view to keeping costs under control and passing those savings on to you.

About the Authors
Nigel Cheshire: With more than 20 years of experience in the software industry, Nigel Cheshire is CEO of Enerjy Software, the creator of tactical software tools for Java developers. Nigel's past experience also includes founding Teamstudio, Inc., the leading provider of Lotus Notes/Domino development tools. He was a principal at Ives and Company, a CRM-solutions provider, and a member of the R&D team with Data General Corporation. Nigel holds a bachelor's degree in computer science from the University of Teesside, England.
Richard Sharpe: Richard Sharpe is a technical support specialist at Enerjy Software. He previously worked for IBM in the E-Business Group for a number of years and then joined Aspective Ltd in the Mobile Business Group as a WebSphere/Java specialist. Richard holds a bachelor's degree in Computing Systems from Nottingham Trent University, England and is a certified WebSphere Application Server Systems Expert.

Reference