Coding standards help you to improve code readability, produce consistent code, and prevent error-prone coding styles. Robert Buckley adds a note on MISRA-C and coding standards.

June 16, 2006
URL:http://www.drdobbs.com/tools/code-quality-improvement/tools/code-quality-improvement/189401916

JunHo and YoonKyu are engineers at Samsung Electronics' Software Labs. They can be contacted at [email protected] and [email protected], respectively.

To overcome critical software development challenges and reduce development costs, the software engineering field has developed practices such as requirements engineering, analysis and design technologies, process engineering, and the like. Many of these practices apply to the implementation phase of development; for example, coding standards, refactoring, inspection, and static analysis. Among them, coding standards are the fundamental way to improve code readability, help individual developers produce consistent code, and prevent error-prone coding styles.

Samsung Electronics has focused on improving code quality by defining and enforcing internal coding standards. We—the QA team—used a coding standards conformance checker for this purpose, but we did not regularly apply this initial checking tool to our software development. Because of tool weaknesses, we used it only sporadically during final audits. As a result, we saw only minimal improvement to code quality.

More recently, we evaluated Parasoft's C++test and applied it throughout an on-going project ("Mobile"). In this article, we describe our experiences and share what we learned. Here, a "coding standards item" is a guideline described in the company's coding standards or conformance documents; a "coding standards rule" (or just "rule") is a codified programming rule in an automated coding standards tool.

Samsung Electronics is a major consumer electronics company. Although Samsung started as a hardware-centric vendor, software is quickly becoming a major concern for us, as it is for most other consumer electronics vendors. The Mobile project is a Samsung Electronics C/C++ development project designed to develop a reusable and extensible object-oriented software framework mainly targeting mobile devices. Our QA team is an independent group responsible for testing software produced by Samsung Electronics. We invest considerable time evaluating automated tools in an effort to minimize routine work.

C/C++ Coding Standards

The Mobile project uses a set of project-specific coding standards derived from general Samsung coding standards. The Mobile project standards could be rewritten by taking into account the language variances and other development constraints. For example, some compilers used in the Mobile project do not support exception handling. Therefore, it is impossible to detect resource allocation failures while an object's constructors are called. The Mobile project solves this problem by employing the well-known two-phase object construction technique described in the Mobile project coding standards: Divide an object initialization into the object allocation phase and the resource allocation phase to return the exception as a value (see Listing One).

    class ResourceManager
    {
       ResourceManager(); // allocate only object
       result Construct(); // allocate resources
                        // 'result' contains error code 
    };
    int main()
    {
       // Two phase construction
    ResourceManager aObject; 
    if (aObject.Construct() == FAIL) 
    printf("Resource allocation is failed");
    }

Additionally, the Mobile project requires rigid conformance to coding standards. This project mainly targets a software framework to be used by other developers; it must be consistent and well organized to facilitate software development on this framework. The more project constraints there are, the greater the necessity for an automated tool. That's why the Mobile project adopted a coding standards checker.

C++test from Parasoft (www.parasoft.com) provides automated C/C++ unit testing, as well as automated coding standards checking. We chose C++test as our coding standards checker because it was the most effective solution for the majority of our considerations.

One of C++test's distinct features is its GUI-based rules. Figure 1 shows the GUI rule description for the rule "Each global variable must be initialized." Whenever a "global variable" is found while parsing the source code, the rule evaluates logic components. A violation is reported if any of the following conditions are not met:

• The detected global variable is an external declaration.
• It does not have an initializer.
• Its type is not an array or a class.

Figure 1: The GUI-based coding standard rules in Parasoft C++test.

The GUI interface simplifies rule creation. Most C++ code checkers require scripting for rule creation; this is difficult and requires more C++ programming knowledge.

GUI-based rules can be easily understood and implemented because the available conditions are shown graphically. Having GUI-based rules could compromise extensibility because only predefined nodes and condition sets can be selected in a GUI. However, C++test provides Python scripting support to ensure extensibility.

Choosing a Coding Standards Checker

Our selection criteria included product usability features, but not specific details (rule selection, rule execution, and scalability). We established these criteria from our experiences with previous coding standards checkers, feedback from project development teams, and product evaluations.

Ability to modify rules. Most coding standards checkers include preimplemented rules. Having built-in rules reduces the rule implementation effort. However, these rules usually do not fully match our coding style. Moreover, because most rules are implemented simply, false positives are common, making the results unreliable. We needed an easy way to customize the rules to exclude exceptional cases, add new rules, or modify the existing rules. Lint-like tools can check some coding standards items, but lack rule customization features. Though some checkers provide parameterization techniques for rule customization, more flexibility is required for modifying rules in detail.

Ability to report coding standards compliance at various levels. Many coding standards checkers support file-level reporting. However, for management purposes, package- and project-level reporting is desirable. For example, project managers often want to review coding standards violations by packages or by projects to identify trends and prioritize the correction of coding standards violations—especially when deadlines are approaching.

Ability to integrate with development environments. Many rule violations can be easily corrected. For instance, violations like "Use tabs instead of spaces to indent" can be corrected by simply replacing the spaces with tabs. In such situations, having a coding standards checker with direct access to the violation source (through tight integration with the development environment) significantly reduces the time required for correction.

Additionally, as a project evolves, it includes more files and more "include/directive" settings. If the checker does not run inside the IDE, the checker should create project files by importing or synchronizing with IDE project files, such as makefiles, dsp/dsw files, and so on. This saves time configuring the environment for running the checker.

Ability to make unified rules for C/C++. Our major programming languages, C and C++, have a similar structure—except that C++ has more features for object-oriented and generic programming. Maintaining two different rules for the common items in these languages would require extra resources.

Ability to recognize language variation. Compared to C, C++ has a short history. Compiler vendors produced their own C++ compilers before the ISO C/C++ was established and research shows that many C++ implementations do not yet perfectly support C++ ISO Standards (http://www.ddj.com/184405483). Since coding standards checkers usually parse the source code, the supported language variations are significant.

Ability to check unprecompiled header files. Some coding standards checkers lack direct checking for header files. Instead, violations in header files are indirectly reported by checking header file parts in the precompiled implementation files. In this case, violations related to preprocessor directives and comments in header files, which usually contain important information used by other developers, are ignored. Therefore, direct checking of header files is desired.

Experiences Using the Checker

Applying a coding standards checker reduces coding standards violations during implementation. However, the number of violations detected and eliminated depends on the characteristics of the target project and the quality of the coding standards rules. We found that each project has similar overall trends but many different details that impact coding standards checking. Thus, the following results should be viewed as a trend, not in a deterministic manner.

Direct benefits refer to how reducing the number of violations improved code quality. Indirect benefits are other unexpected developer benefits.

Figure 2 shows the overall trend for the number of coding standards violations. To eliminate the effects of rule evolution, we use the latest rule set for all checking. After a relatively steady number of violations between Nov-04 and Jan-05, there was a violation reduction of approximately 1/8 in Feb-05. There was an unexpected increase in violations between Feb-05 and Mar-05, but this was acceptable because the target project was evolving continuously.

Figure 2: The overall number of violations/KLOC.

Figure 3 shows the trend for the number of violations whose corrections impact only the current module. Violations decreased 6.6 percent since the date of checker deployment. This data does not cover comment rules, which usually don't have large change impacts but do require significant change efforts.

Figure 3: The number of violations with small change impacts/KLOC.

Figure 4 shows the trend for the number of violations whose corrections impact more than the current module. Violations decreased 19.6 percent since the date of checker deployment.

Figure 4: The number of violations with large change impacts/KLOC.

One of the unexpected benefits of coding standards checking was the developer education it promoted. Beginners, and even some experienced developers, initially did not understand the meaning and importance of some coding standards items. For example, consider the coding standards item "Prefer initializations to assignments," which is known as an efficient way to initialize member variables in a constructor (see Effective C++, by Scott Meyers; Addison-Wesley, 1992). Some developers did not understand why initializing members in a constructor's initialization list is better than assigning the initial values in a constructor's body. They discussed these issues when reviewing the checker's results. This eventually helped the developers understand C++ features thoroughly, and demonstrates how coding standards checking helps developers learn from their mistakes.

Another indirect benefit was the removal of unrealistic coding standards items. When we applied the coding standards rules to the Mobile project, we found that most developers did not obey the rule "Do not exceed 80 columns per line." This rule was developed because some old development environments had 80-column displays. We examined our development environments and concluded that in our situation, such limited development environments are rarely used and longer columns are preferred. Consequently, we changed the column limitation from 80 to 150 columns per line. This kind of coding standards modification has improved developer buy-in to coding standards compliance.

Lessons Learned

Until recently, our checking involved only the QA team checking coding standards compliance at the project level. This was effective for tracking defect trends and maintaining the rule set. However, there were several drawbacks.

First, the reported violation sources do not always match the code in the development environment. Developers don't usually work on a centralized source-code repository; they write and modify code in a private area, then copy or check-in the source code to the centralized repository. If the development source code differs from the code that QA is testing, it can be difficult for developers to identify and repair the source of reported violations.

Second, developers prefer to immediately verify that a violation correction has eliminated the problem.

For these reasons, we decided to have the coding standards checker run by developers as well as the QA team.

Developers who do not carefully follow standards may produce code with many violations, and are often reluctant to correct the violations. This is especially problematic with violations from identifier- or design-related rules, which are difficult to correct in later development phases because making such corrections can have a large, project-wide impact. We recommend checking coding standards conformance from the early coding phase so that the violated code is corrected before it is propagated out of the module.

One reason why the coding standards checking effort with our previous tool failed was the lack of rule maintenance at the organization level.

After the initial rule set is established, rules should be customized continuously because some rules might not apply to particular projects and development style might vary across development domains. A rule set should be maintained throughout each project's operations as the project constraints evolve.

Automatic coding standards checking should complement code reviews. In our development process, code review is mandatory because it effectively catches developers' logical errors and mistakes. However, developers nevertheless skip code reviews due to schedule constraints. Our experiences and research show that some developers are easily distracted by style issues and focus on them during code reviews (D. Kelly and T. Shepard, "Qualitative Observations from Software Code Inspection Experiments"; CASCON, 2002). Consequently, some developers view the code review process as being time-consuming with little benefit, and then skip it. This can be prevented by removing coding standards violations with automatic coding standards checking before the review, which allows the review to focus on finding logical and serious errors. Moreover, because automatic checking covers only about 50 percent of the items in our coding standards (some items are complicated to implement with an automated tool), code reviews are needed to check the remaining items.

Conclusion

We have applied the checker to several projects in our organization and achieved significant code-quality improvements in each case. We plan to apply it to additional projects and analyze the effects on code quality.

Terms of Service | Privacy Statement | Copyright © 2024 UBM Tech, All rights reserved.