The Psychology of Quality and More

C Style: Standards and Guidelines (contents)

CHAPTER 3 : General Principles

PART 1 : BASICS

CHAPTER 3 : General Principles

3.1 Keywords

3.2 Think of the reader

3.3 Keep it simple

3.4 Be explicit

3.5 Be consistent

3.6 Minimize scope

3.7 There's no one true style

3.8 A standard which isn't used, isn't a standard

3.9 Distinguish between standards and guidelines

3.10 Standards don't guarantee good coding

3.11 Decide on your portability quotient

3.12 Standards are a function of their audience

3.13 Keep project standards

3.14 Use standard libraries

3.15 Utilize available tools

3.16 Summary

<--Prev page | Next page -->

3.3 Keep it simple

This is a simple principle, which has been immortalized in a slim volume entitled 'The KISS Principle'. KISS stands for, "Keep It Simple, Stupid!"

C is itself a simple language in which, paradoxically, its simplicity gives it power and consequent potential for significant complexity.

The code is largely treated by the compiler as a simple character stream, so layout can vary widely. Expressions have few restrictions and there is a rich collection of operators. The power of pointers is legion.

It is very easy to write code which is concise and understood by the writer. However, with a little extra thought, it could be made much simpler.

Sometimes there may be a penalty for simplicity, in terms of additional code or slower execution. There is a program-dependent balance between performance and simplicity in which it is easy to err in either direction. The end user of the program doesn't care how the program is written, just so long as it works correctly, quickly and within reasonable memory and disk bounds. However, the maintainer cares a great deal, and the end user will suffer in the end if it takes a long time to correct or change the code. Style should only be sacrificed for speed or space in known bottlenecks, and not as matter of course.

A danger of simplicity is to take it too far, and to affect clarity as a result. If variable names are too short or if comments are not used, then the code might appear beautifully simple, but still be very difficult to understand. Thus the following code fragment may appear to be quite simple, but its purpose is still unclear:

if ((v = vpos(vs)) > vmax || vp != vp2 && h < hmax)

    for (v = 0, h = hmin; h < hmax << 2; vinc(vs), hinc(hs));

<------------------------------------------------------------>

The obverse of simplicity is complexity. Complexity increases with the number of variables and operators in an expression, and with increasing levels of nesting. It causes the reader's short term memory to overflow, causing significant thrashing between it and working memory, with the attendant potential for error.

Note that this principle can equally be applied to the coding standards themselves. A dense and complex set of standards will not get fully used (if at all). Both in the selection of items to standardize upon and in their presentation, the KISS principle can be well applied. Thus a minimization exercise might have to be performed on a set of standards which is particularly detailed, or a set of standards written by someone unaccustomed to documentation might be rewritten and reformatted.

<--Prev page | Next page -->