Coding Standards and Guidelines

In formal reviews, the inspectors are looking for problems and omissions in the code. There are the classic bugs where something just won't work as written. These are best found by careful analysis of the codesenior programmers and testers are great at this.

There are also problems where the code may operate properly but may not be written to meet a specific standard or guideline. It's equivalent to writing words that can be understood and get a point across but don't meet the grammatical and syntactical rules of the English language. Standards are the established, fixed, have-to-follow-them rulesthe do's and don'ts. Guidelines are the suggested best practices, the recommendations, the preferred way of doing things. Standards have no exceptions, short of a structured waiver process. Guidelines can be a bit loose.

It may sound strange that some piece of software may work, may even be tested and shown to be very stable, but still be incorrect because it doesn't meet some criteria. It's important, though, and there are three reasons for adherence to a standard or guideline:

• Reliability. It's been shown that code written to a specific standard or guideline is more reliable and secure than code that isn't.

• Readability/Maintainability. Code that follows set standards and guidelines is easier to read, understand, and maintain.

• Portability. Code often has to run on different hardware or be compiled with different compilers. If it follows a set standard, it will likely be easieror even completely painlessto move it to a different platform.

The requirements for your project may range from strict adherence to national or international standards to loose following of internal team guidelines. What's important is that your team has some standards or guidelines for programming and that these are verified in a formal review.

Examples of Programming Standards and Guidelines

Figure 6.2 shows an example of a programming standard that deals with the use of the C language goto, while, and if-else statements. Improper use of these statements often results in buggy code, and most programming standards explicitly set rules for using them.

Figure 6.2. A sample coding standard explains how several language control structures should be used. (Adapted from C++ Programming Guidelines by Thomas Plum and Dan Saks. Copyright 1991, Plum Hall, Inc.)

The standard has four main parts:

• Title describes what topic the standard covers.

• Standard (or guideline) describes the standard or guideline explaining exactly what's allowed and not allowed.

• Justification gives the reasoning behind the standard so that the programmer understands why it's good programming practice.

• Example shows simple programming samples of how to use the standard. This isn't always necessary.

Figure 6.3 is an example of a guideline dealing with C language features used in C++. Note how the language is a bit different. In this case, it starts out with "Try to avoid." Guidelines aren't as strict as standards, so there is some room for flexibility if the situation calls for it.

Figure 6.3. An example of a programming guideline shows how to use certain aspects of C in C++. (Adapted from C++ Programming Guidelines by Thomas Plum and Dan Saks. Copyright 1991, Plum Hall, Inc.)

IT'S A MATTER OF STYLE

There are standards, there are guidelines, and then there is style. From a software quality and testing perspective, style doesn't matter.

Every programmer, just like every book author and artist, has his or her own unique style. The rules may be followed, the language usage may be consistent, but it's still easy to tell who created what software.

That differentiating factor is style. In programming, it could be how verbose the commenting is or how the variables are named. It could be what indentation scheme is used in the loop constructs. It's the look and feel of the code.

Some teams do institute standards and guidelines for style aspects (such as indenting) so that the look and feel of the code doesn't become too random. As a software tester, when performing formal reviews on a piece of software, test and comment only on things that are wrong, missing, or don't adhere to the team's accepted standards or guidelines. Ask yourself if what you're about to report is really a problem or just difference of opinion, a difference of style. The latter isn't a bug.

Obtaining Standards

If your project, because of its nature, must follow a set of programming standards, or if you're just interested in examining your software's code to see how well it meets a published standard or guideline, several sources are available for you to reference.

National and international standards for most computer languages and information technology can be obtained from:

• American National Standards Institute (ANSI), www.ansi.org

• International Engineering Consortium (IEC), www.iec.org

• International Organization for Standardization (ISO), www.iso.ch

• National Committee for Information Technology Standards (NCITS), www.ncits.org

There are also documents that demonstrate programming guidelines and best practices available from professional organizations such as

• Association for Computing Machinery (ACM), www.acm.org

• Institute of Electrical and Electronics Engineers, Inc (IEEE), www.ieee.org

You may also obtain information from the software vendor where you purchased your programming software. They often have published standards and guidelines available for free or for a small fee.