Perform explicit tests to determine success, true/false, and equality to improve the readability and maintainability of code and for compatibility with common conventions.
In particular, do not default the test for nonzero. For instance, suppose a
foo() function returns 0 to indicate failure or a nonzero value to indicate success. Testing for inequality with 0,
is preferable to
despite the convention that 0 indicates failure. Explicitly testing for inequality with 0 benefits maintainability if
foo() is later modified to return −1 rather than 0 on failure.
This recommendation is derived from and considers the implications of the following common conventions:
- Functions return 0 if false and nonzero if true [StackOvflw 2009].
- Function failures can typically be indicated by −1 or any nonzero number.
- Comparison functions (such as the standard library function
strcmp(), which has a trinary return value) return 0 if the arguments are equal and nonzero otherwise (see strcmp function).
Noncompliant Code Example
In this noncompliant code example,
is_banned() returns 0 if false and nonzero if true:
If a banned user is listed twice, the user is granted access. Although
is_banned() follows the common convention of returning nonzero for true,
processRequest checks for equality only with 1.
Because most functions guarantee a return value of nonzero only for true, the preceding code is better written by checking for inequality with 0 (false), as follows:
Noncompliant Code Example
In noncompliant code, function status can typically be indicated by returning −1 on failure or any nonnegative number on success. This is a common convention in the standard C library, but it is discouraged in ERR02-C. Avoid in-band error indicators.
Although failures are frequently indicated by a return value of 0, some common conventions may conflict in the future with code in which the test for nonzero is not explicit. In this case, defaulting the test for nonzero welcomes bugs if and when a developer modifies
validateUser() to return an error code or −1 rather than 0 to indicate a failure (all of which are also common conventions).
Although the code will work as intended, it is possible that a future modification will result in the following:
In this code, the programmer intended to add error code functionality to indicate the cause of a validation failure. The new code, however, validates any invalid or nonexisting user. Because there is no explicit test in
processRequest(), the logical error is not obvious and seems correct by certain conventions.
This compliant code is preferable for improved maintenance. By defining what constitutes a failure and explicitly testing for it, the behavior is clearly implied, and future modifications are more likely to preserve it. If a future modification is made, such as in the previous example, it is immediately obvious that the
if statement in
processRequest() does not correctly utilize the specification of
Noncompliant Code Example
Comparison functions (such as the standard library
strcmp() function) return 0 if the arguments are equal and nonzero otherwise.
Because many comparison functions return 0 for equality and nonzero for inequality, they can cause confusion when used to test for equality. If someone were to switch the following
strcmp() call with a function testing for equality, but the programmer did not follow the same convention as
strcmp(), the programmer might instinctively just replace the function name. Also, when quickly reviewed, the code could easily appear to test for inequality.
The preceding code works correctly. However, to simplify the login code or to facilitate checking a user's password more than once, a programmer can separate the password-checking code from the login function in the following way:
In an attempt to leave the previous logic intact, the developer just replaces
strcmp() with a call to the new function. However, doing so produces incorrect behavior. In this case, any user who inputs an incorrect password is granted access. Again, two conventions conflict and produce code that is easily corrupted when modified. To make code maintainable and to avoid these conflicts, such a result should never be defaulted.
This compliant solution, using a comparison function for this purpose, is the preferred approach. By performing an explicit test, any programmer who wishes to modify the equality test can clearly see the implied behavior and convention that is being followed.
Code that does not conform to the common practices presented is difficult to maintain. Bugs can easily arise when modifying helper functions that evaluate true/false or success/failure. Bugs can also easily arise when modifying code that tests for equality using a comparison function that obeys the same conventions as standard library functions such as
|Supported indirectly via MISRA C:2004 Rule 13.2.|
|Axivion Bauhaus Suite|
|LDRA tool suite|
|114 S||Partially implemented|
Avoid comparing values with TRUE macro/enum constant using equality operators ("==", "!=")
Partially supported: reports comparisons of Boolean values to constants other than 0
|[StackOvflw 2009]||"Should I Return TRUE/FALSE Values from a C Function?"|