The syntax of a programming language tells you what code it is possible to write—what machines will understand. Style tells you what you ought to write—what humans reading the code will understand. Code written with a consistent, simple style is maintainable, robust, and contains fewer bugs. Code written with no regard to style contains more bugs, and may simply be thrown away and rewritten rather than maintained.

Attending to style is particularly important when developing as a team. Consistent style facilitates communication, because it enables team members to read and understand each other's work more easily. In our experience, the value of consistent programming style grows exponentially with the number of people working with the code.

Our favorite style guides are classics: Strunk and White's The Elements of Style and Kernighan and Plauger's The Elements of Programming Style. These small books work because they are simple: a list of rules, each containing a brief explanation and examples of correct, and sometimes incorrect, use. We followed the same pattern in this book. This simple treatment—a series of rules—enabled us to keep this book short and easy to understand.

Some of the advice that you read here may seem obvious to you, particularly if you've been writing code for a long time. Others may disagree with some of our specific suggestions about formatting or indentation.

A complete treatment of programming principles and software design is clearly beyond the scope of this book. However, this chapter includes some core principles that we have found to be central to good software engineering.

Engineering

Do Not be Afraid to Do Engineering

The ultimate goal of professional software development is to create something useful—an engineering task much more than a scientific one. (Science is more immediately concerned with understanding the world around us, which is admittedly necessary, but not sufficient, for engineering.)

Resist the temptation to write code to model scientific realities that include all theoretical possibilities. It is not a “hack” to write code that has practical limitations if you are confident those limits do not affect the utility of the resulting system.

For example, imagine you need a data structure for tree traversal and choose to write a stack. The stack needs to hold at least as many items as the maximum depth of any tree. Now suppose that there is no theoretical limit to how deep one of these trees can be. You might be tempted to create a stack that can grow to an arbitrary size by reallocating memory and copying its items as needed. On the other hand, your team's understanding of the application may be such that in your wildest imagination you'd be amazed to see a tree with depth greater than 10. If so, the better choice would be to create a fixed-length stack with a maximum of, say, 50 elements.

As commercial developers of software components, we always strive to have good, consistent style throughout our code. Since source code is usually included in our final products, our users often study our code to learn not just how the components work, but also how to write good software.

This fact ultimately led to the creation of a style guide for Java™ programming, entitled The Elements of Java Style. The positive reception to that book, coupled with recurring questions about C++ style issues, resulted in this edition for C++.

If you've read The Elements of Java Style (or even if you haven't), much of the advice in this book will probably be familiar. This is deliberate, as many of the programming principles described are timeless and valid across programming languages. However, the content has been reworked and expanded here to address the unique characteristics of the C++ language.

Audience

We wrote this book for anyone writing C++ code, but especially for programmers who are writing C++ as part of a team. For a team to be effective, everyone must be able to read and understand everyone else's code. Having consistent style conventions is a good first step!

This book is not intended to teach you C++, but rather it focuses on how C++ code can be written in order to maximize its effectiveness. We therefore assume you are already familiar with C++ and object-oriented programming.

Developers often forget that the primary purpose of their software is to satisfy the needs of an end user; they often concentrate on the solution but fail to instruct others on the use of that solution.

Good software documentation not only tells others how to use your software, it also acts as a specification of interfaces and behaviors for the engineers who must help you develop the software and those who will later maintain and enhance it. While you should always make every attempt to write software that is self-explanatory, your end users may not have access to the source code; there will always be significant information about usage and behavior that a programming language cannot express.

Good programmers enjoy writing documentation. Like elegant design and implementation, good documentation is a sign of a professional programmer.

Document Your Software Interface for Those Who Must Use It

Document the public interface of your code so others can understand and use it correctly and effectively.

The primary purpose for documentation comments is to define a programming contract between a client and a supplier of a service. The documentation associated with a method should describe all aspects of behavior on which a caller of that method can rely and should not attempt to describe implementation details.

Describe each C++ element that appears in, or forms part of, the interface.

Document Your Implementation for Those Who Must Maintain It

Document the implementation of your code so others can maintain and enhance it.