Customizing Coding Standards With RuleWizard

Table of Contents

• Introduction
• The Need for Custom Coding Standards
  • Preventing Errors from Reoccurring
  • Measuring Metrics
  • Adapting Core Coding Standards to a Particular Project or Team
  • Implementing Naming Conventions
• Customizing Coding Standards With RuleWizard
• Conclusion
• Availability

Introduction

Enforcing a set of coding standards has been proven to effectively prevent errors from entering code. As a result of its ability to prevent errors, coding standards enforcement...

• Reduces the number of bugs shipped to end users
• Results in faster time to market
• Reduces development and support costs

The effects of these benefits are maximized when development teams enforce custom coding standards (standards unique to a company, development team, or project) as well as core coding standards (standards recognized and enforced by developers around the world). This paper will discuss circumstances in which custom coding standards can heighten a development team's error prevention efforts, then describe the most efficient and effective way to enforce custom coding standards.

The Need for Custom Coding Standards

Custom coding standards are particularly useful in four instances:

• Preventing errors from reoccurring
• Measuring metrics
• Adapting core coding standards to a particular project or team
• Implementing naming conventions

Preventing Errors from Reoccurring

One of the best ways to improve software quality and development efficiency is for each developer to perform the following process each time that he or she finds an error:

1. Determine why the error was introduced.
2. Design and enforce a coding standard that prevents this error and similar errors from occurring.

If developers perform this process for every error that they detect, they will quickly build a set of coding standards that can prevent their teams' most common errors from ever entering their code.

Measuring Metrics

A metric is a measurement of a specific attribute or pattern of attributes in a piece of code. For example, a metric might measure the total lines of code in a file, or the total number of global/shared references in a C++ class. Metrics do not target problematic constructs; rather, they make measurements that can be used to assess what areas of code may be especially prone to problems. When metrics are used consistently and are tracked across multiple team or company projects, they can also be used to make determinations about project length, cost, and status.

Tracking what is most important for a certain team or project often requires the creation of customized metric rules. For example, a team that tends to have a high number of errors in classes with deep hierarchies might want to measure the number of ancestors of every class; this will help them keep their hierarchies under control and, by doing so, reduce the number of errors that they introduce into the code. Another team that rarely has errors in classes with deep hierarchies might want to only measure the class inheritance level of classes that derive from over 20 base classes, a depth which may make a class difficult to reuse.

Adapting Core Coding Standards to a Particular Project or Team

Sometimes developers may want to enforce a certain coding standard, but find that it does not quite fit the team's project, development philosophy, and/or style. For example, suppose a development team wants to apply the standard "Never overload &&, || or ," that is found in Scott Meyers' More Effective C++. However, this standard is not appropriate for their project because they have already exposed an API to their customers that includes overloading && for some user-defined types. They do not want to break their API, but they want to enforce this rule for all other types. Their predicament could be solved by customizing the existing standard so that a violation is only reported if the overloading is not required by the existing API.

Implementing Naming Conventions

There are two forces at work as a developer writes code. The first force is the need to write the code itself. The second force is the need to connect the code to real life. When it is time to check code for errors, the developer must make a correlation between these two forces. He or she can then debug the algorithm and determine whether the logic is correct. Therefore, it is best to write code that is as easy to read and understand as possible. When developers choose names for variables, they should use words that connect the variables to real life. Using standard naming conventions is most reliable way to connect code to its real-life function.

Bad code:

 public class ba {
     public final static String curr = "dollars";
 
     public void dep (int i) {
         bal += i;
     }
     public void wit (int i) {
         bal -= i;
     }
     public String get () {
 	 return Integer.toString (bal) + " " + curr;
     }
 
     private int bal;
 }

The developer who wrote the above code did not use naming conventions. Any medium-sized code written this way will be very difficult to understand, even by the original writer, because it is just code. At a glance, nobody can tell what the code does. To determine the function of this code, developers will have to figure out what each abbreviated variable name stands for. Their minds will be forced to make the constant translation of "ba" into "BankAccount" and "dep" into "deposit" at the same time that they are supposedly checking the function of the code.

The key to successful error prevention is to allow the brain to focus on only one issue at a time. The human brain is far more accurate when it compartmentalizes tasks, and accuracy is of utmost importance in preventing errors. By using naming conventions, the developer frees his mind to check the logic of the code and focus on real problems.

There is another advantage to using standard naming conventions: developers can apply real life experience and intuition to code checking. Intuition is important in checking code for the same reason that it is important in understanding mathematics. Students who have trouble with algebra in high school often lack the ability to connect equations to real life. To them, algebra is a meaningless jumble of numbers and letters, and the process of solving a problem remains a mystery. However, when students learn to connect the problems to real life, they often show a marked improvement in their ability to reach a correct answer. They are now using intuition and applying life experience to problems. The application of intuition is also essential to testing the logic of an algorithm.

Furthermore, not adhering to naming conventions can have lasting detrimental effects on the productivity of a development group. Developers who join the group later will be confused by abbreviations that don't follow a particular pattern, and time spent sorting out confusion is wasted time in the development cycle. Even the original writer may become confused while writing without standard naming conventions because he or she must assign and remember abbreviations for a long list of variables.

Developers generally know they should follow naming conventions, but they fail to do it because they think it is easier to use abbreviations. However, the few extra seconds a developer spends using standard naming conventions today can save hours of extra work for the development group later in the development cycle.

Good code:

 public class BankAccount  {
     public final static String CURRENCY = "dollars";
 
     public void deposit (int amount) {
         _balance += amount;
     }
     public void withdraw (int amount) {
         _balance -= amount;
     }
     public String getBalance () {
 	 return Integer.toString (_balance) + " " + CURRENCY;
     }
 
     private int _balance;
 }
 

The above code has been written using standard naming conventions. Because the developer writing the code used the variables "BankAccount", "deposit", "withdrawal", and "balance" instead of "ba", "dep", "wit", and "bal", it is clear that this code is meant to add and subtract money from a bank account and display the final balance. This code is also easier to write, because the programmer writing it doesn't need to improvise when deciding what abbreviations to use.

With good naming conventions in place, the developer can apply life experience when checking code. Nearly everyone has had the experience of depositing to and withdrawing from a bank account; this experience is useful in determining whether a program that performs these functions is working correctly.

Because naming conventions often vary from development team to development team, enforcing them often requires the creation of custom coding standards.

Customizing Coding Standards With RuleWizard

In response to the growing need to enforce a wide variety of custom coding standards, ParaSoft decided to include RuleWizard in its automatic source code analysis tools. RuleWizard allows developers to graphically design custom coding standards that can be enforced automatically. RuleWizard can be used both to create new coding standards and to modify built-in coding standards.

Because it is possible to make mistakes in any programming language, RuleWizard is available for a wide variety of languages; versions are available for:

• C/C++
• Java
• HTML, Cascading Style Sheets, and JavaScript

Support for additional languages will be added soon. Each edition of RuleWizard is integrated into one of ParaSoft's automatic source code analysis tools, which can enforce both built-in and custom coding standards with a single command or click of a button. CodeWizard for C/C++ enforces C and C++ coding standards, Jtest enforces Java coding standards, and WebKing enforces HTML, CSS, and JavaScript coding standards.

With RuleWizard, developers can design and modify coding standards (or "rules") by graphically expressing the pattern that they want their ParaSoft source code analysis tool to look for when it parses code. Rules are created by selecting a main "node," then adding additional elements to a flow-chart-like representation until it fully expresses the pattern that constitutes a violation of the rule. RuleWizard contains an extensive library of nodes that can be used as building blocks for the rules, as well as a wide variety of options to express the relationships that should or should not exist between the nodes; this means that RuleWizard can be used to create and implement a virtually unlimited set of custom coding standards.

RuleWizard is very easy to learn and use. Rules are built by pointing and clicking to add graphical representations of rule elements, then using dialog boxes to make any necessary modifications. No knowledge of the parser is required to write or modify a rule. In fact, RuleWizard is so easy to use that a beginning RuleWizard user can usually create and implement a rule which enforces corporate naming conventions in 15 minutes or less.

Developers can use RuleWizard to create the following types of rules:

• Personal coding standards that prevent each error detected from reoccurring
• Rules that enforce metrics
• Personalized versions of built-in coding standards
• Naming conventions

For each rule that is created, RuleWizard automatically generates HTML-format documentation based on the rule properties and descriptions that the rule's author entered. This documentation can then be posted in a location where all developers abiding by these coding standards can easily access the complete documentation for any rule.

Conclusion

One of the most effective ways to prevent errors is to enforce coding standards. Coding standard enforcement is most successful when:

• The set of standards enforced includes a substantial group of standards that are perfectly tailored to the development team to which they will be applied.
• Developers have a fast and easy way to enforce all of their coding standards.

RuleWizard and ParaSoft's automatic coding standards enforcement tools let developers create custom coding standards in minutes, and enforce an entire set of custom and built-in coding standards with the click of a button. This translates to releasing a higher quality product, faster, with lower development costs.

Availability

RuleWizard is currently available as a feature of CodeWizard, Jtest, and WebKing. CodeWizard and Jtest are both available at ; WebKing is available now at http://www.thewebking.com. To learn more about how CodeWizard, Jtest, WebKing, and other ParaSoft development tools can help your department prevent and detect errors, talk to a Software Quality Specialist today at 1-888-305-0041, or visit .