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.

This book is meant to serve pedagogical and practical purposes by presenting a process called Bridge, which instantiates generic aspects of software methods including iteration and traceability. It also presents seven case studies documented in Unified Modeling Language (UML). The process and case studies are preceded by an overview of object-oriented modeling artifacts that act as a background for developing the concepts in the process and for presenting the case studies.

The book is appealing for a variety of readers because it provides a comprehensive view of modeling artifacts and how they fit together in an iterative context to provide working solutions. The approach that it adopts has the advantage of cutting down the learning curve and of bridging the gap between theory and practice. Readers will learn from the experience of other developments. The underlying theme is that a considerable amount of learning is achieved through practical applications of the theories involved; teaching object-oriented development could be made more effective by relying on documented practices.

This book is adequate for an introduction to object-oriented software development for pedagogical, training, and practical purposes. The first part is appropriate for a course on object-oriented development, whereas the second part on the case studies provides the meat for technical training. In addition, we believe that novices in practical contexts would benefit from this book, which cuts down the learning curve. Software engineers seeking to add rigor to their techniques would also find this book useful.

INCEPTION

USER REQUIREMENTS

User requirements are a summary of information that is collected by customers asking travel agencies about tours that the travel agencies offer. From that information we deduced the user requirements, shown in Description 3-1.

Constraints

For simplicity, we made two assumptions. The first one is that the customer can only reserve a single tour. Consequently, he is assigned a login ID and a password. The second assumption is that the customer can optionally reserve as many trips as he wants in his tour reservation. For example, suppose that the travel agency company provides a tour to Athens. Then the customer who chooses this tour can optionally choose one or more trips related to the Athens tour such as a trip to the temples or a tour to Olympus.

WEDDING LIST

A software for a wedding agency provides a gift reservation facility for couples who would like to have a wedding list, and a gift purchase facility for people who would like to send gifts. The software keeps information on couples and their corresponding wedding lists. Users can access the system to create or update, cancel, view their own wedding list, or to buy certain items from a specific wedding list. Users can also get help on how to use the system without the trouble of contacting employees at the wedding agency. Employees at the agency will administrate the system operations. Employees can delete, update, or add items to inventory. Any complaints or suggestions that the client may have could be sent to the agency and stored in a complaint database. To ensure secure access to the system couples and employees have personal logins and passwords.