The Psychology of Quality and More

C Style: Standards and Guidelines (contents)

Preface

<--Prev page | Next page -->

There has long been a popular image of the programmer as a 'hacker', not crafting programs with science but carving them out of naked stone. The typical programmer is characterized in a popular article, 'Real programmers don't use Pascal', which differentiates the 'real' programmer from the 'quiche-eaters' who use 'structured programming' and 'methodologies' thus:

"* Real programmers aren't afraid to use GOTOs.

* Real programmers don't need comments - the code is obvious.

* Real programmers write programs, not documentation. Leave that to the maintenance people."

Although this article contains exaggerations, its popularity and humor lies in the fact that it contains a lot of home truths, not only about the 'hackers' but also about their potential demise:

"What of the future ? Real programmers are very concerned because the latest generation of computer programmers is not being brought up with the same outlook on life as their elders."

Programmers are now called software engineers. And 'standards' is no longer a dirty word. Standards bodies are established and respected, and organizations are hurrying to implement new standards in many areas of computing. The mention of programming style, however, still is guaranteed to raise a hackle or two. There is wide recognition that style standards are a good idea, but there is often little agreement on the nitty-gritty of what and how to standardize. C, in particular, is a language in which there is plenty of scope for widely varying styles.

"If you ignore the fact that it's 'structured', even 'C' programming can be appreciated by the real programmer: after all, there's no type checking, variable names are seven (ten? eight? thirty two?) characters long and the added bonus of the pointer data type is thrown in - like having the best parts of FORTRAN and assembly language in one place (not to mention some of the more creative uses for #define)."

The strengths of C are also its weaknesses. It's lack of constraint enables many ways of programming the same function, from high-level structured programming to low-level bit twiddling. C is very good for concise programming, where the programmer's concern for brevity can easily obscure the real meaning of the code and can leave hazards for the unwary maintainer. The following piece of code was used as an example of good programming by a university lecturer (including the comment!):

case 'A': if ( condition )

case 'B': statement; /* C - we love you */

Teachers of programming are primarily concerned with what you can do with the language, rather than how easy it is for another programmer to understand it. Books on the language also have a focus on the use of the language (although better books do show some consideration of style). Authors are heavily constrained by the space available and their examples are usually quite concise. This is possible in a book, as the examples are usually made more understandable by the accompanying text.

A professional programmer should not only be able to write efficient and correct code, he should also be able to write it in a style that others, who may have to maintain it years later, will understand. It is a fundamental consideration within this book, that programmers should use style not so much for themselves as for other readers of their code, such that the reader will easily understand (and not misunderstand) the code.

Such is the nature of the human mind, that errors of understanding can occur at the simplest level. Take, for example, the effect of the following two styles of representing the continuation of expressions across lines:

Style 1: Variable1 = Variable2

+ Function3();

Style 2: Variable1 = Variable2 +

Function3();

Someone accustomed to Style 1, on reading Style 2 may miss the '+' at the end of the first line (the ever-helpful brain possibly turning it into a semicolon), and read the second line as a function call, albeit indented incorrectly. Similarly the person accustomed to Style 2 may misinterpret Style 1.

The word 'religion' is commonly used when describing programmers' attitudes to some points of style. A religious point can usually be detected by the presence of several opposing 'schools of thought' about which is the right style. Viewed objectively, one style seldom has particular merit over the others. 'Religion' describes a situation of faith, where adherents are often blind to other points of view.

Given this plethora of styles and religions, it would be unrealistic for this book to attempt to create a single inflexible style standard for C. Instead, it discusses many of the problems of coding style in C, often leaving the final decision as to what is the best alternative to you, the reader. It aims to empower you to create your own standards, rather than imposing what may be arbitrary decisions (but which should be made, one way or another). It is not a book of standards. Rather, it is a book about standards.

So who is this book for? You, the reader, may well belong to one of the following groups:

1. A professional or student programmer, who wants to understand and improve your own programming style.
2. A member of a programming team, aiming to define coding standards for your group.
3. A member of a company quality department, aiming to define company coding standards.

Most books are limited by the size of the printed word, rather than what the author has to say on the topic, and this book is no exception. The guiding principle used here is to include those topics which might reasonably be found in a set of company coding standards. Such standards tend to vary widely both in size and scope, yet they fall into several general categories. This book is divided into sections to reflect these categories, with some extra parts to explain why standards are needed, and how they might be implemented:

Basics

There are fundamental reasons why standards are needed, and guidelines can be derived for selecting standards. Understanding why is an important step in helping to generate some guiding principles for deciding what should be standardized.

Commenting and Naming

Comments and identifier names together make all the readable English in the code. Individually and collectively they describe the program and help the reader to understand the meaning of the code.

Layout

The layout of the code, from the high-level file organization to the placing of braces is an important element of style. Changing layout can make the familiar become unfamiliar.

Usage

The way code is used has a notable effect not only on the readability of the code but also other factors, such as portability and performance.

Implementation

Standards do not work unless they are accepted and (hopefully) agreed to by the people who will use them. They also need defined processes for ensuring they are used and how they may be updated.

There are some topics which are often covered in coding standards, such as portability or performance, but which are large enough to be the subject of whole books on themselves. In these cases, the topic is discussed in that detail which was found to be most commonly covered in coding standards.

Finally, although I have tried to keep my own religions out of the discussion, there will be inevitable situations where some faith will still creep through. There will almost certainly be situations where you will violently disagree. There will also, I hope, be situations where you equally violently agree. As with coding it is you, the reader, who must judge the value of the point. In any case, if you are caused to come to a reasoned conclusion which helps you to write more certain coding standards, then this book will have succeeded.

David Straker

January 1991

<--Prev page | Next page -->