Coding Guidelines

It is quite common for coding guideline documents to contain at least one guideline recommending against the use of a construct that developers very rarely use. For instance “The operand of the sizeof operator shall not contain side-effects.”

Why do such guideline recommendations get incorporated into documents. The obvious answer is that their author(s) are unaware of actual developer usage and believe the recommendation has value.

I have heard people claim that such guideline recommendations are harmless; after all, the adherence cost is minimal. Besides, the fact that code very likely already adheres to it will increase the “pass” rate for the set of guidelines the first time developers check their code. However, such guidelines unjustifiably increase peoples confidence in software (as measured by the number of guidelines adhered to). They not only fail to add value to a set of coding guidelines, but their presence could result in the probity of the other guidelines being questioned.

I have been surprised by the amount of resistance met by my attempts to have the “sizeof” guideline removed from, or not included in, a set of coding guidelines. In the case of an existing set of guidelines there is obviously a resistance to change, but I have failed to extract a single promise to consider removing the guideline in a future revision.

People seem unimpressed by the amount of source code I have searched in a vain attempt to find a violation of the “sizeof” guideline. They often have memories of having seen an instance of this elusive usage. My questions asking after the name of the source file, the name of the program, the name of the project, or simply the name of the company they were working for at the time are greeted with uncertainty. Perhaps the only instance they have seen is in the example underneath the text of the recommendation? Growls and pointed looks.

Another factor is existing practice. If it appears in other guideline documents it must have some benefit. People don’t want to go out on a limb. Besides, basing decisions on measurement of source code, who does that these days?

Whatever else might be said about the “sizeof” guideline, it does make a great example that developers can use to regale management.

Superior tone: Less experienced developers
Earnest voice: don't always have a complete understanding of C/C++
Shock: They make the mistake of thinking
Talk very fast: that the code sizeof i++
Incredulity: will cause i to be incremented!
Emphasis: This guideline
Relieved voice: ensures that this mistake is not made.


Producing a set of coding guideline recommendations is expensive and time consuming. A growing number of guideline authors are stumbling across a process that they think will enable them to quickly produce a set of high quality guidelines for relatively little investment. The process takes as its starting point the constructs listed as having undefined, implementation defined, and unspecified behaviors, by a language standard. The items on this list are filtered, often reworded and expanded with commentary, numbered, and formatted into an impressive looking document (example).

Given the pedigree of the original source material it might be thought that it would be difficult to produce a document that did not have some modicum of quality, and that with some investment of effort a high quality document could be produced. In fact, for anything other than the mostest-lowest cost set of guidelines (perhaps for a small company that cannot afford better) this approach has a number of serious flaws.

These flaws are errors of omission and commission.

Only starting with the behaviors listed in the standard means that the human element is not considered. What of those constructs whose use is known to be a common source of developer mistakes? A large class of constructs, having significant economic impact, has been excluded from consideration. Also, not all constructs are explicitly called out as having undefined, implementation defined, or unspecified behavior. See the committee response to DR 017 question 19 for an example.

What of the list of constructs that are considered? The requirements of coding guideline authors were not considered (at least for C and C++) by the authors of language standards when deciding which constructs should have undefined, implementation defined, or unspecified behaviors. Factors that were considered include:

• Simplifying the wording in the standard. For instance, in C … the order of evaluation of subexpressions and the order in which side effects take place are both unspecified. This means that the assignment x=y; exhibits unspecified behavior (e.g., is x evaluated before y, or vice versa?). By casting a very wide net the C committee have caught all the edge cases they wanted to catch in a single sentence; they have not had to go to the trouble of individually calling each of them out. Ok, so a lot of harmless cases are caught in the same net, but who cares? Well, any program that contains an assignment statement will violate any best practices based on guideline recommendations that prohibit the use of constructs that have unspecified behavior.

• Clarifying intent. For instance, the C Standard says of the register storage-class that The extent to which such suggestions are effective is implementation-defined. The authors of the standard are making it very clear that implementations are not required to place objects declared using this storage class in a register. The choice of which objects are held in a processor register is always going to be implementation defined, whether it is explicitly called out by a language standard or not. Recommending against the use of the register storage-class, as MISRA does, purely because it appears in a list of implementation-defined behaviors shows a complete lack of insight.

• Politics (i.e., satisfying the demands of some constituency). For instance, in C90 the result of integer division when either of the operands is negative is implementation-defined (one of two possibilities has to be chosen). The user constituency (as represented by the C committee) for one of the possibilities was sufficiently non-existent that a single result was specified in C99.

The real danger of any guideline recommendations based on a list of behaviors called out by a language standard is that superficially they look quite good. It does not take much expertise to produce them and their inherent weakenesses will not be visible to the casual reader.

The possibility of faults in software causing death or serious injury is often talked about and in some cases large amounts of money are invested in work to reduce the possibility of these events occurring. The Therac-25 accidents are an often quoted example of a software fault that directly resulted in deaths. These accidents occurred over a 19 month period in the mid 1980s and are believed to have resulted in the death of six people. I don’t wish to disrespect the memory of the people who died, but six people 20 years ago; is that it? Less than the number of people killed every day (around 10) in traffic accidents in the UK.

If faults in software really do have a non-trivial impact on human safety then we would expect this fact to be reflected in accident statistics. After searching the accident statistics for the UK I cannot find any whose cause is directly attributed to software. If there are people who have died as a direct result of faults in software, the death rate has not yet reached the minimum level needed to be recorded as such (or are these deaths ‘hidden’ away in ones and twos within other causes?)

The US National Transportation Safety Board carries out a thorough investigation of all US aviation accidents. Searching the Aviation Accident Database on the query “software” between the dates 1 Jan 2000 and 9 Aug 2005 returns 44 matches. Reading these 44 reports I did not find any accident attributed to a software related issue.

If faults in software are not killing or seriously injuring many people why is so much effort invested in reducing the probability of these events occurring? The following are some of the possibilities:

• The investment actually made is small, but it is talked up.

• The investment is made for economic reasons (e.g., more reliable products are likely to reduce support costs) and increased ’safety’ is a side effect.
• In situations where there is a likelihood of death or serious injury the procedures and reliability of non-software items is sufficient to short-circuit the effects of any life threatening faults that may exist in the software used (at least until the fault can be corrected).

As any developer knows, replicating faulty behavior in software can be very difficult, if not impossible. It may be that software faults are not given as the root cause of death or serious injury because the necessary proof is not available. Or perhaps software faults have yet to be the root cause of such events on any non-trivial scale.

Existing practice affects what people are willing to put up with. Many users of Microsoft Windows now accept that it is necessary to reboot the computer they are using on a daily, or even hourly, basis. Users of cars accept that the tool they are using can result in serious injuries or even death (usually rating nothing more than a story in the local town newspaper). Will there be a public hue and cry once software faults start to be recorded as a primary factor in accidental death or serious injury? As this paper shows, it can take a lot of dead bodies before existing practices are changed.

The lack of dead bodies suggests that it is very still early days for the field of high integrity software development.

It is quite common for coding guideline documents to recommend against the use of uninitialized variables (e.g., MISRA C rule 9.1). In many cases the authors of such a rule are mindlessly following the path of being seen to be worthy (who could argue that such a recommendation is not good practice), or are just copying those recommendations that appear in two or more other guideline documents.

Do developers really need to be told that they should not use uninitialized variables? I hope not. I have always thought of coding guideline as being recommendations not to do something that developers might otherwise have thought acceptable. In some cases the reason for developers thinking that a particular usage is acceptable might be because they have misunderstood the language semantics. The authors of coding guidelines need to assume some minimum level of developer expertise, and I think the use of uninitialized variable usage falls within the bounds of what we can assume developers know.

So am I saying that a recommendation covering the use of uninitialized variables is a waste of time? I wish I could. In practice the recommendations contained within coding guideline documents are often given a special status: they are the only coding rules that management pays attention to.

How do developers justify spending time adhering to a coding rule that is not contained in the guideline document specified by the customer? Why should the tool vendors who claim to detect violations of guideline recommendation invest in detecting constructs that are not recommended against. While specialist tool vendors might consider the ability to perform many different kinds of checks as a selling point, compiler vendors don’t consider checking for guideline conformance as the primary selling point of their tools.

What of the public image of a coding guidelines document? The benefits of adhering to the recommendations contained in this document have to be sold to a variety of audiences. Not everybody would know what an uninitialized variable was if it fell on their foot. How can a guideline document be any good if it fails to recommend against such usage?

When push comes to shove I am willing to take the easy way out and to write the appropriate recommendation. But on my own time I sometimes ignore the peanut gallery.

Writing coding guidelines for computer languages is a popular activity (although actually following them seems to be much less popular). While there is nothing to suggest that Java will be an exception, it is possible that in some circumstances they could be unpopular with Sun.

One such circumstance might be safety critical applications (where there is a significant risk of loss of life or serious injury if unpredictable behavior occurs). A high integrity ad hoc group has been set up to investigate the possibility of producing coding guidelines for languages used to write such applications. Current thinking is that a set of language independent guidelines will be created and interested parties (perhaps subgroups within the ad hoc group) will map these to language specific guidelines. This group is still in the early stages and has yet to attract any interest from Java users (or at least Java traffic on the its internal discussion list).

Sun have already red flagged the use of Java binaries in some applications. The Java binary license includes the words:

…Licensee acknowledges that Licensed Software is not designed or intended for use in the design, construction, operation or maintenance of any nuclear facility…

One method for Sun to gain some protection for themselves would be to hand over control of the language to an International committee. However, ever since I represented the UK at the first Java study group meeting in January 1997 ( formed with the intent of investigating the possibility of creating an ISO standard for Java) it has been obvious that Sun are not willing to give sufficient copyright permission to ISO, or rights to the Java name. This desire to hang on to Java continues to this day.

It is possible that Sun might be willing to countenance the publication of an International Standard called J (for instance) that happened to be almost identical to the Java language. ISO has been here before; the name of the language specified in ISO/IEC 11756:1999 is M, not MUMPS (Massachusetts General Hospital lay claim to this name). Also, while there is no standard for Javascript, an ECMAscript Standard does exist.

Safety critical applications are a niche market. Is there a worthwhile benefit to Sun in having a suitable set of coding guidelines for Java? The potential litigation costs may cause Sun to want to stay away from this area. However, such a move is likely to have a negative impact on peoples perception of the reliability of applications written in Java.

Until the SC22 ad hoc group is further along in its deliberations Sun can ignore the issue. But at some point Java developers are going to start being involved with coding guidelines and will be seeking input from Sun.