“Failure to supply contemporaneous rationale for design decisions is a major defect in many software projects. Lack of accurate rationale causes issues to be revisited endlessly, causes maintenance bugs when a maintainer changes something without realizing it was done a certain way for some purpose, and shortens the useful lifetime of software.”
—Beman Dawes, on the Boost website
“Rationale is fairly easy to provide at the time decisions are made, but very hard to accurately recover even a short time later.”
—The Boost website
Steve McConnell contends in Code Complete, [McConnell1993], that software development should really be termed software engineering. Conceding this to be an accurate statement, we further recognize (based upon the experience of the more traditional engineering disciplines) that all decisions—even the most common and apparently trivial—must thus be considered in light of their ramifications to the final product.
A good engineer does more than provide a solution “that works.” He definitely has to do that, but a good engineer is also concerned about:
These are often competing goals and that is why, when developing software, a good engineer must provide deliverables (such as source code and other documentation) that:
Thus, reliable engineering consists of more than just solutions to the problems an engineer faces; it also consists of documenting decisions, such that, any engineer viewing the original engineer’s deliverables will not have to struggle to understand the problems that faced the original engineer, how that engineer solved those problems and the rationale behind those solutions (thus making it easier to determine whether those decisions completely meet a given set of design goals—whether the original goals or some new set of goals intended to extend the original design. Decisions do not exist in a vacuum.
For software development purposes, all decisions can be classified as either an “engineering practice” or a “stylistic preference.” Within the context of software development, engineering practices are those practices that express, and make plain, critical choices in source code and other deliverables, whether the ultimate object code or executing program is directly effected or not. Although some programmers view a stylistic preference as any practice or choice that, when changed, does not effect the resulting object code, when such a “stylistic preference” is used to make a code critical choice more self-evident to a code reviewer, it should properly be viewed as a reliable engineering practice. Take, for example, providing a comment documenting why a particular algorithm was used (or not used), or providing some indication (stylistically or with a comment) of whether a declared function will modify a passed in object. Neither actually modify the resulting object code, but both should be viewed as necessary engineering practices because they are essential to meeting the general guidelines of quality engineering.
Although stylistic preferences can be quite personal, they should, at a minimum, be chosen in such a way that the meaning of any piece of code is readily apparent to a junior engineer without extensive study. A description of the stylistic preferences we follow when using C, C++ and Objective-C can be found in our Style Guidelines.
This document, however, is a list of various software engineering practices—both generally speaking and as they relate to C, C++ and/or Objective-C—that, when followed, lead to better, more maintainable software. It attempts to bring together rules, guidelines, and practices that are scattered throughout other sources and reflects the programming community’s best tried-and-true experience. Rationale is often provided so that the rules can be understood rather than just memorized.
Although we are mindful of the following quote:
“Undertake not to teach your equal in the art he himself professes; it savors of arrogancy.”
—One of 110 rules of civility copied by a young George Washington
from a sixteenth century French book of etiquette.
…one of the purposes of this document (and our Style Guidelines) is to stimulate discussion among software engineers about what constitutes reliable engineering practices and any stylistic preferences that will help make those practices more clear. We do not claim to have a corner on the market for these ideas—as you will see, many of those mentioned in our documents came from published books—, but we do believe there should be a central repository for such ideas. Not so much to presume to “undertake to teach our equals in the art they themselves profess,” but so more people can apply them in a uniform manner and thereby improve the quality of software any group of engineers chooses to produce.
Any text in this document that is this color should be considered incomplete and still under construction.
The sections of this document have subsections labeled as follows:
Introduces and provides the necessary background information to understand subsequent maxims.
Maxims answer who, what, where, when and how.
Provides examples and discussion expounding upon the maxim(s).
Discusses the benefits of (i.e., the why), and the consequences of ignoring (i.e., the why not), the maxim(s).
Lists known exceptions to the maxim(s).
Lists references that contain more information about the topic at hand.
Understand the five major distinct memory stores, why they are different, and how they behave.
Although the distinction between Free Store and Heap, as here defined, is technically accurate, in everyday use, the term Heap is often used when Free Store is meant.
The const data area stores string literals and other data whose values are known at compile-time. No objects of class type can exist in this area. All data in this area are read-only and available during the entire lifetime of the program.
Global or static variables and objects have their storage allocated at program startup, but may not be initialized until after the program has begun executing. For instance, a static variable in a function is initialized only the first time program execution passes through its definition. The order of initialization of global variables across translation units is not defined.
Shared data increases coupling and therefore should be avoided, if possible.
See Item 10 of [Sutter2005a].
The stack stores automatic variables. Objects are constructed immediately at the point of definition and destroyed immediately at the end of the same scope (but the order in which variables are stored on the stack cannot be portably assumed). Stack memory allocation is typically much faster than for dynamic storage (i.e., Free Store or Heap).
The free store is one of the two dynamic memory areas and is allocated and deallocated using new and delete.
Always provide both class specific operator new(params) (or new[]) and class specific operator delete(void*, params) (or delete[]) if you provide either.
(See Item 45 of [Sutter2005a].)
If you provide any class-specific new, provide all of the standard forms (plain, in-place, and nothrow).
(See Item 46 of [Sutter2005a].)
The heap is the other dynamic memory area and is allocated and deallocated by malloc(), calloc(), realloc() and free().
Note that while the default global operators new and delete might be implemented in terms of malloc() and free(), the heap is not the same as free store, and memory allocated in one area cannot be safely deallocated in the other.
According to the C++ standard, memory for the heap must not be implemented in terms of new/delete.
Prefer using the Free Store (and employ reliable ownership practices). Avoid using the Heap.
The Basic, Strong, and No-fail (formerly known as No-throw) guarantees were originally defined with respect to exception safety, however they really apply to all failure handling, regardless of the specific method used to report failure. The No-fail guarantee is a strict superset of the Strong guarantee, which is a strict superset of the Basic guarantee. Failure to meet at least the Basic guarantee is always a bug and difficulty in making any piece of code satisfy the Basic guarantee is almost always is a signal of poor design.
See Items 8 thru 12 in [Sutter2000], Items 22 thru 23 in [Sutter2002], and Item 71 of [Sutter2005a].
A function with the No-fail guarantee will not fail under any circumstances. Overall exception safety is not possible unless certain functions (e.g., destructors, deallocators, and the Swap() function) are guaranteed not to fail. Somewhat surprisingly, C++ exception specifications are of limited usefulness when providing this guarantee.
A function with the Strong guarantee means that, if the operation fails, program state will remain unchanged. This always implies commit-or-rollback semantics, including that no references or iterators into an object become invalidated if an operation fails.
A function with the Basic guarantee means that, if the operation fails, no resources are leaked and objects remain in a destructible and usable—but not necessarily predictable—state. All, some or none of the function’s postconditions may be met but all of a type’s invariants are always reestablished.
Always provide at least the Basic guarantee.
Every function should provide the strongest guarantee it can without needlessly penalizing calling code that does not need the guarantee. Where possible, it should additionally provide enough functionality to allow calling code that needs a still stronger guarantee to achieve that.
The documentation for each function should, at a minimum, declare which of the three standard failure guarantees is being met. (Consider versioning: It is always easier to strengthen a guarantee, but weakening a guarantee breaks calling code that has come to rely on the stronger guarantee without notifying the client.)
Clients should not have to inspect implementation details in order to know what to expect.
See Item 71 of [Sutter2005a].
All software defects fall into one of the following categories:
This section has been deprecated until some point in the future when we will likely have to incorporate Item 69 (a rational error handling policy) of [Sutter2005a].
Before design goals can be met, design goals must be specified. For an entire software project, this often takes the form of a Requirements Specification or something similar, however for an individual class or type, this often takes the form of a few paragraphs at the top of the class’s interface file.
Documentation intended for use outside of a development team (e.g., a user’s manual, a ReadMe file, etc.) should be kept outside of the source code used to produce the software (object code). (Such documentation may be “code based” itself—so that it can be “generated” at different stages—, but the salient point is that it has a different target audience and usually a different set of people working on it.)
On the other hand, development team documentation should be stored physically as close to what is being documented as practical.
Users of source code should not be required to search for documentation covering the code they wish to use. The documentation should be where clients are going to look anyway, viz., in a class’s interface file.
Documentation intended for clients of a class should be completely within the class’s interface file.
Documentation related to implementation details of a class should be within the class’s implementation file.
Write for correctness, simplicity and clarity first.
See Item 6 of [Sutter2005a].
Obviously an engineer’s deliverables must meet the prescribed design goals. That is to say, the ultimate user will only remain a user if the software does what the user needs it to do.
#include guardsC++ does not allow some information—often part of .h files—to be declared or defined more than once.
For specifics, consult section 9.3.3 of [Stroustrup1997].
Every .h file should contain #include guards, preventing the contents of the .h file from being #included elsewhere multiple times.
(See also our comments about #pragma once.)
Consult our Style Guidelines for an example.
Clients will not receive errors if more than one interface file they include #includes your interface file.
main()Although your compiler may recognize others, the C++ standard only recognizes two signatures for main().
Always use either of the two standard and portable declarations for main():
int main(void);
int main(int argc, char* argv[]);
Portability.
Virtual functions only mostly behave virtually; inside constructors and destructors, they do not.
Avoid calling virtual functions (or other functions that rely on virtual functions) in constructors and destructors.
See Item 49 of [Sutter2005a].
An interface should attempt to delineate “Design by Contract,” i.e., each function declaration should specify the expected preconditions and the delivered postconditions. Quite often this can be effectively accomplished via the careful specification of parameter types. Member functions also implicitly guarantee to maintain a type’s invariants.
Unit testing (including test-driven development) and code coverage tools are particularly useful in validating that functions and methods actually fulfill “Design by Contract.”
Clients can expect contracted behavior and know that, if they do not receive it, the problem is not theirs. In other words, encapsulation can be relied upon.
Abstract interfaces help you focus on getting an abstraction right without muddling it with implementation or state management details.
Prefer to design hierarchies that implement abstract interfaces that model abstract concepts.
Prefer to define and inherit from abstract interfaces.
Prefer to follow the Dependency Inversion Principle, which states:
See Item 36 of [Sutter2005a].
There are different kinds of classes. Know which kind you are designing. (This maxim is based primarily upon C++; its general concepts apply in Objective-C, although the rules tend to be less stringent.)
typedefs and static functions.
It has no modifiable state or virtual functions.std::exception.Based primarily on Item 32 of [Sutter2005a].
Functions cannot rely upon callers to be well-behaved, therefore…
Every function must validate its preconditions (i.e., starting assumptions). (Parameter verification and ensuring a pointer is non-NULL are classic examples of preconditions.) If a function is internal to a module, it should assert each of its preconditions, otherwise it should report precondition violations by emitting an appropriate error.
Clients are not allowed to use a type incorrectly.
A condition should be a precondition if and only if it is reasonable to expect all callers to verify the condition’s validity before calling the function.
See Item 70 of [Sutter2005a].
It is reasonable for a function to validate another called function’s postconditions (i.e., ending assumptions). Because the called function can always be viewed as internal to the calling function’s module, postconditions can be asserted or reported to a caller by emitting an error, as the design dictates.
Errors in, or misuse of, suppliers are more likely to be caught and dealt with.
See Item 70 of [Sutter2005a].
Invariants are a special kind of postcondition that applies to member functions and whose violations should be asserted.
Clients should not be able to set an object of a given type to a state that violates that type’s invariant. Therefore, any type containing a member variable that is not allowed to have its full range of values (based on the invariant of that member variable’s type) must be designed so the member variable is private and accessible only through accessors.
Types are always internally consistent.
See Item 70 of [Sutter2005a].
When client programmers use a function incorrectly, the function should detect and flag such incorrect use (at least in a debugging configuration).
Failure to recognize and signal incorrect usage allows client programmers to use types or classes of objects in ways for which they were not designed, and thus allow situations that are likely to behave unpredictably.
Every function that accepts parameters should verify that each passed in argument is within the range of reasonable values for the abstraction the parameter refers to. This is a precondition of the function.
Assuming you are maintaining a type's invariants, the object pointed to by the this (or self) parameter can typically be assumed to be correct.
Clients can assume that, if (a debugging version of) a function does not complain about the arguments being passed in, the function is being used correctly.
Before dereferencing any pointer, it must be verified to be non-zero.
Because the compiler automatically passes the this (or self) parameter, it can typically be assumed to be non-NULL (except after object initialization in Objective-C).
It should not need to be said that results are unpredictable when accessing an area of memory from a NULL pointer. Furthermore, it should not need to be said that, having a pointer with a non-NULL, yet invalid value, is asking for trouble.
typename over classthis qualifierMost modern compilers provide optional mechanisms to warn engineers when they try to do something potentially hazardous or potentially non-portable. Such warnings are diagnostic messages that report constructs that are not inherently erroneous but are risky or suggest there may have been an error. These warnings typically have some sort of work-around to sidestep the warning.
Some examples of these types of warnings include:
Every project should enable all tenable language warnings that notify engineers when they try to do something potentially hazardous.
Such warnings require engineers to type in a work-around and thus make explicit their consideration of these hazardous choices.
When a type or class’s interface (i.e., its contract with the outside world) is modified in a significant manner, clients of that interface should receive compile and link time (or, at a minimum, runtime) warnings, errors or signals.
Changes to types or classes that have an effect on clients should cause those clients to fail to compile so that client engineers are forced to take notice of the change and modify their code to work correctly with the newly modified type or class. Failure to flag the change could cause clients to be using the “new” type or class incorrectly, resulting in incorrect behavior.
Put all entities with linkage in implementation files.
Eliminates link time errors and memory waste.
See Item 61 of [Sutter2005a].
When modeling “is implemented in terms of,” always prefer membership/containment, not inheritance. Use private inheritance only when inheritance is absolutely necessary—that is, when you need access to protected members or you need to override a virtual function.
Consult the summary of Item 22 in [Sutter2000]. Additionally, because of the Interface Principle, if you do not prefer containment, you may discover surprising effects in your code. See Items 31-34 in [Sutter2000].
See also Item 34 of [Sutter2005a].
Avoid inheriting from classes that were not designed to be base classes. Using a standalone class as a base is a serious design error and should be avoided. To add behavior, prefer to add nonmember functions instead of member functions. To add state, prefer composition instead of inheritance.
See Item 35 of [Sutter2005a].
Public inheritance means substitutability (i.e., “works-like-a”). Never inherit publicly to reuse code (in the base class); inherit publicly in order to be reused (by code that uses base objects polymorphically).
See Item 37 of [Sutter2005a].
When overriding a virtual function, preserve substitutability; in particular, at a minimum, you must observe the function’s pre- and postconditions from the base class.
See Item 38 of [Sutter2005a].
Multiple-inheritance is fraught with peril.
Avoid multiple-inheritance from more than one non-protocol class.
Always make base class destructors either public and virtual, or protected and nonvirtual.
Any class that has only the implicit (nonvirtual) destructor or an explicit nonvirtual destructor cannot be a base class.
See Item 50 of [Sutter2005a].
When providing a function with the same name as an inherited function, be sure to bring the inherited function(s) into scope with a using-declaration (if you do not want to hide them).
When a derived class deliberately hides a base class’s functionality, it should do so explicitly by writing a private using-declaration.
Immutable values are easier to understand, track and reason about.
The const and mutable qualifiers are our friends.
Use const proactively; as much as possible, but no more.
Do not cast away const (except to call a const-incorrect function).
See Item 15 of [Sutter2005a].
mutable over const_castSome uses of const_cast are dangerous (e.g., if the compiler places the object in read-only memory).
If possible, prefer using mutable over const_cast.
See Item 94 of [Sutter2005a].
Automatic (stack based) variables should always be initialized as part of their declaration.
Constructors (and initializers) should always initialize every member variable into some valid state. (In Objective-C, this sometimes means simply leaving a member variable at its default value of zero. In such a case, you should be explicit that zero was intended and assert the value as zero in the initializer method.) In other words, objects always have invariants, and a fully constructed object either reflects that invariant or never existed because an exception was thrown. (See also using initializer lists.)
If an initializer method cannot fully construct all member variables, it should autorelease itself and return nil.
Always verify that an alloced/inited object is non-nil before using it.
Clients can rely on the fact that objects are always in a valid state (or unsuccessfully constructed and construction failure indicated—in C++, with an exception thrown, or in Objective-C, because self was set to nil).
In each function, take all the code that might fail and do all that work safely off to the side. Only then, when you know that the real work has succeeded, should you modify the program state and clean up using non-throwing operations.
Types whose member functions provide this Strong guarantee are more easily reused.
See Items 9 & 10 in [Sutter2000].
According to the C++ standard, the order in which function arguments are evaluated is undefined and compiler implementation dependent.
Never write code that depends on the order of evaluation of function arguments.
Portability. (Evaluation of multiple function arguments as part of a function call is essentially a compound statement and should therefore be avoided even when portability is not a consideration.)
See Item 31 of [Sutter2005a].
Never change the default argument(s) of overridden inherited functions. (This is one more reason why “magic numbers” are to be avoided. The default argument values will be needed by derived classes.)
See Item 38 of [Sutter2005a].
See section 14.4 of [Stroustrup1997].
Always use “resource acquisition is initialization” (aka, RAII) to isolate resource ownership and management.
Here, “resource” can mean many different types of resources such as: memory, thread locks, file writing permission, etc.
(The ScopeExitAction family of classes (in our osi namespace) is a general facility designed to simplify implementing precisely this maxim.)
Exceptions will not cause resource leaks.
See Item 13 of [Sutter2005a].
A free store object is one whose memory is allocated via new, and the owner of a free store object is whomever is responsible for deleting it when it is no longer needed.
When you need to specify the transfer of ownership of a free store based object, use std::auto_ptr or osi::shared_ptr (or something similar).
Because auto_ptr and shared_ptr are designed to take on ownership of free store objects and appropriately delete such objects, even within the context of exceptions, specifying auto_ptr and shared_ptr makes the intended assumption of ownership plain and virtually impossible to ignore.
Doing so intentionally makes it impossible for clients to refuse to relinquish ownership of an object (when you are taking on that responsibility), or, when they need to accept ownership of an object, it makes it harder for them to not recognize that they are assuming responsibility for deleting the object.
The best treatise I have seen on this topic is Item 37 in [Sutter2000].
Memory allocations can throw and the order of execution of multiple allocations within a single statement (e.g., in a function call) can be compiler dependent.
Perform every explicit resource allocation in its own source code statement, which immediately gives the allocated resource to a manager object.
The best treatise I have seen on this topic is Item 21 in [Sutter2002], but see also Item 13 of [Sutter2005a].
You can never treat arrays polymorphically.
Prefer using vector (or string) instead of arrays.
See Item 77 of [Sutter2005a].
Unions can be abused into obtaining a “cast without a cast.”
Do not use unions to reinterpret representation.
See Item 97 of [Sutter2005a].
typename over classIn template declarations, prefer the typename keyword over the class keyword.
A template type T often could be int, which is not a class.
this qualifierWithin class template member functions, always use the this-> qualifying construct.
Do:
this->Swap();
-NOT-
Swap();
See Section 5.2 of [Vandevoorde2003].
Function templates cannot be partially specialized nor can function template specializations be overloaded.
When extending someone else’s function template, avoid trying to write a specialization; instead, write an overload of the function template and place it in the namespace of the type(s) the overload is designed to be used for.
For a class:
namespace N {
class SomeClass {/*...*/};
} // namespace N
…prefer:
namespace N {
void swap(SomeClass& rtOp, SomeClass& ltOp);
} // namespace N
…over:
namespace std {
void std::swap(SomeClass& rtOp, SomeClass& ltOp);
} // namespace std
When writing your own function template, prefer to write a single function template that should never be specialized or overloaded, and implement the function template entirely in terms of a class template.
See Item 66 of [Sutter2005a].
A predicate is a function object that returns a boolean answer. Algorithms make an unknowable number of copies of their predicates at unknowable times in an unknowable order, and then go on to pass those copies around while casually assuming that the copies are all equivalent.
Do not allow predicates to hold or access state that affect the result of their operator().
Prefer to make operator() a const member function of predicates.
The compiler can help prevent modifying the state of the function object.
See Item 87 of [Sutter2005a].
Comparers for associative containers must be function objects. Function objects are adaptable and typically produce faster code than functions.
Prefer function objects over functions as algorithm and comparer arguments.
See Item 88 of [Sutter2005a].
Function objects, like function pointers, are typically passed by value.
Where possible, make function objects cheap to copy and adaptable by inheriting them from unary_- or binary_function.
See Item 89 of [Sutter2005a].
Using-directives—e.g., using namespace std—cause wanton namespace pollution by bringing in potentially huge numbers of names, many of which are unnecessary.
Never write namespace using-directives in header files.
Using-declarations—e.g., using std::strlen—contribute to namespace pollution on a more minor level.
Never write namespace using-declarations in header files.
Placing a using-directive or a using-declaration before a #include statement can introduce unintentional changes in semantics for the included file.
Within implementation files, never write a using-directive or a using-declaration before any #include directive(s).
See Item 59 of [Sutter2005a].
With the introduction of namespaces, the old C-style standard library headers (e.g., stdio.h) have been deprecated.
Prefer the new C++ standard library headers (e.g., cstdio).
Use namespaces wisely. If you write a class in some namespace N, be sure to also put all helper functions and operators into namespace N.
See the Interface Principle in Items 32 & 33 in [Sutter2000], and Item 57 of [Sutter2005a].
Use namespaces wisely. Keep types and functions in separate namespaces unless they are specifically intended to work together.
See Item 58 of [Sutter2005a].
The C/C++ languages provide certain functionality for every type or class, whether the author of the type wants it or not. This turns out to be a mixed blessing. Take for example, a programmer defined class in C++:
class Empty {};
It automatically receives the following implicit (compiler provided) functionality (when, but only if, the compiler requires it):
Empty(void) // A default constructor
Empty(const Empty&) // A copy constructor
~Empty(void) // A destructor
Empty& operator=(const Empty&) // A copy assignment operator
Empty* operator&(void) // Address-of operators
const Empty* operator&(void) const
The correctness of compiler provided “implied” functions must always be evaluated and documented.
(The most troublesome tend to be the copy constructor and operator=.)
Within a given access qualifier section (i.e., public, protected, private), these functions should occur in a consistent order so that clients can easily find them and determine whether they are explicitly defined, implicitly defined, or whether clients are explicitly prevented from invoking such behavior (and the reasons why; whether such functionality is perceived to not be needed or whether it cannot be provided with available resources, or whatever).
Our recommendation (admittedly a stylistic preference) for this order is as shown above, viz.: Constructors should be the first member functions within an access qualifier section.
The default constructor, if any, should be listed as the first constructor.
The copy constructor should be listed as the last constructor (to keep it closer to operator=, which it is similar to).
The destructor should immediately follow the constructor list.
operator= should immediately follow the destructor.
The two operator& are rare and should follow operator=.
If a class provides a Swap() function, it should follow any explicit declarations of (or comments regarding) these potentially implicit functions.
If a class provides a Clone() function, it should follow Swap().
This section is strongly influenced by Item 45 in [Meyers1998] and Items 52 & 53 of [Sutter2005a]. You are encouraged to read them for more details on this issue.
operator=Swap()Clone()The compiler provides the implicit default constructor only when no other constructor is declared.
When relying on the implicit default constructor, failure to state, “The implicit default constructor is acceptable” leaves implicit something clients need to know has been explicitly considered.
Such a statement means this type has no constructors other than the implicit default constructor, and the implicit default constructor works correctly. This is hardly ever the case for complex classes. The presence of other constructors obviates the need to make a statement concerning the default constructor.
Passing an object by value means, by definition, call the copy constructor. The implicit copy constructor provides memberwise copying.
The behavior supplied by the implicit copy constructor is clearly incorrect for some types. For example, relying on the implicit copy constructor for types that contain data members that are pointers to free store objects is a common but subtle source of bugs.
Whenever you modify the number or types of data members of a class, you must always consider (or reconsider) how the class copies itself. One of three things must be done:
Classes that do not provide one of the above three statements, must be considered incomplete, if not incorrect.
Often times the person performing a copy is a client who quite naturally assumes that, “if the compiler lets me do it, it must be okay to do.” As the designer of a class, you are the one who knows whether the data members of that type can safely be copied or not. Make explicit your determination by following this maxim. At the same time, you will prevent subtle bugs caused by clients using your types in ways you failed to prevent.
A POD is a Plain Old Data type; i.e., one with C-compatible layout.
Do not memcpy or memcmp non-PODs.
Doing so violates the C++ type system.
See Item 96 of [Sutter2005a].
The implicitly provided destructor is always nonvirtual.
Failure to provide an explicit destructor means the class cannot be a base class.
Failure to state, “The nonvirtual, implicit destructor is acceptable” leaves implicit something clients need to know has been explicitly considered.
Clients see explicit evidence concerning whether the class is designed to be a base class or not.
operator=The implicit operator= provides memberwise copy assignment.
The behavior supplied by the implicit operator= is clearly incorrect for some types.
For example, relying on the implicit operator= for types that contain data members that are pointers to free store objects is a common but subtle source of bugs.
Whenever you modify the number or types of data members of a class, you must always consider (or reconsider) how the class assigns itself. One of three things must be done:
operator= that properly assigns the data members of the class (see also next maxim).operator= within a private access qualifier section, thereby preventing the objects of the class from being assigned by clients.operator= is acceptable.”Classes that do not provide one of the above three statements, must be considered incomplete, if not incorrect.
Often times the person performing an assignment is a client who quite naturally assumes that, “if the compiler lets me do it, it must be okay to do.” As the designer of a class, you are the one who knows whether the data members of that type can safely be assigned or not. Make explicit your determination by following this maxim. At the same time, you will prevent subtle bugs caused by clients using your types in ways you failed to prevent.
For the sake of exception safety (and ease of maintenance), operator= should usually be implemented in terms of the copy constructor.
A reasonable operator= looks like this:
T&
operator=(const T& rtOp)
{
T temp(rtOp); // Does the work?
this->Swap(temp); // See section on Swap()
return *this;
}
When provided as above, operator= carries the Strong guarantee as long as the copy constructor does.
The above also obviates the need to check for assignment to self.
For particularly complex objects, or those where assignment to self is likely, such a check may be performed; but in such a case, it is an efficiency tradeoff not a functional accuracy consideration.
See Item 55 of [Sutter2005a].
These are rare and provide no dangerous side effects, so there is no need to provide any kind of comment when the implicit address-of operators are acceptable.
Swap()The Swap() function is not implicit, however…
In order to implement strongly exception safe copy assignment, the non-throwing Swap() member function is virtually indispensable.
It should be declared like this:
void Swap(T& other); // throw()
See Item 51 & 56 of [Sutter2005a].
Clone()The Clone() function is not implicit, however…
Avoid slicing; in base classes, consider Clone() instead of copying.
See Item 54 of [Sutter2005a].
Constructors that are not declared explicit and that require only one argument to be called—they may be constructors that take multiple parameters with all except the first having default arguments—may be used by a compiler to implicitly convert an object of one type to a new, temporary object of another type.
Avoid implicit conversions by declaring all constructors explicit.
See Item 40 of [Sutter2005a].
operator==() and operator<() (and other operators in terms of them)op() in terms of operator op=()When deciding whether an operator should be a member or a non-member, follow this guideline:
The C++ standard requires that operators =, (), [], and -> must be members,
and class-specific operators new, new[], delete, and delete[] must be static members.
For all other operator functions:
If the function is operator>> or operator<< for formatted stream I/O,
or if it needs type conversions on its leftmost argument,
or if it can be implemented using the class’s public interface alone:
Make it a nonmember (and friend if needed in the first two situations),
If the function needs to behave virtually:
Add a virtual member function to provide virtual behavior, and implement the nonmember in terms of the virtual member function;
otherwise:
Make it a member.
Improved encapsulation.
This entry is based on comments contained in Item 20 of [Sutter2000] (and the errata for that item) and Item 44 of [Sutter2005a].
For value types “do as the ints do”; that is, follow the semantics of the built-in types.
See Item 26 of [Sutter2005a].
operator==() and operator<() (and other operators in terms of them)Implement operator!=() in terms of operator==().
Implement operator>() in terms of operator<().
Implement operator<=() in terms of operator<().
Implement operator>=() in terms of operator<().
This preserves the natural semantics between the operators and they are less likely to diverge during maintenance. They are also less likely to surprise clients.
op() in terms of operator op=()Many operators op (e.g., +, *, |) have an op= equivalent (e.g., +=, *=, |=).
For any given class, if you supply a standalone version of operator op (e.g., operator+) always supply an assignment version of the same operator (e.g., operator+=) and implement the former in terms of the latter.
operator+ should be implemented in terms of operator+= thus:
T&
T::operator+=(const T& rtOp)
{
// Do whatever it takes to perform +=
return *this;
}
const T
T::operator+(const T& ltOp, const T& rtOp)
{
T temp(ltOp);
temp += rtOp;
return temp;
}
This preserves the natural semantics between the two operators and they are less likely to diverge during maintenance. They are also less likely to surprise clients.
See Item 27 of [Sutter2005a].
Clients have expectations of certain operations, such as: postincrement and preincrement are essentially the same thing (with the return value being the only difference).
The postincrement operator for a class T should generally be implemented in terms of its preincrement operator. In other words, it should be as follows:
const T
T::operator++(int /*postincrement*/)
{
T old(*this);
++*this;
return old;
}
This preserves the natural semantics between the two operators and they are less likely to diverge during maintenance. They are also less likely to surprise clients.
Always return ostream or istream references (respectively) from operator<< and operator>>.
This permits chaining; e.g., cout << a << b.
operator delete()Errors are violations of preconditions, postconditions and invariants. Exceptions are superior to error codes for reporting errors because:
Prefer using exceptions over error codes to report errors. Use status codes when exceptions cannot be used or to report conditions that are not errors.
The sections on preconditions, postconditions and invariants each discuss when an error should be thrown as an exception and when it should simply be asserted.
See Item 72 of [Sutter2005a].
Throw exceptions by value and catch them by reference (usually to const).
When rethrowing an exception, prefer throw over throw e.
(Consider our rethrow_() debugging macro.)
This avoids making extra copies and eliminates the potential for object slicing.
See Item 73 of [Sutter2005a].
Do not allow exceptions to propagate across module boundaries.
At a minimum your application must have catch-all catch(...) seals in these places:
main()See Item 62 of [Sutter2005a].
operator delete()Destructors and deallocation functions can be called during stack unwinding as the result of a thrown exception. Throwing a second exception will cause the program to terminate. Therefore, all destructors and deallocation functions should provide the No-fail guarantee.
Implement destructor and deallocation functions as though they had an exception specification of throw().
If a destructor calls a function that has the potential of throwing, always wrap the call in a try/catch block that prevents the exception from escaping.
Clients can throw exceptions and expect that your type will not cause an undesirable termination of the program.
See Item 51 of [Sutter2005a].
try blocksA function try block is not the same thing as a normal try block. (See Items 17 & 18 of [Sutter2002].)
Constructor function try block handlers are really only good for translating an exception. Destructor function try blocks have no practical use because destructors should never emit an exception. All other function try blocks have little or no practical use.
If you make use of unmanaged resource acquisition—which should really be avoided—in a constructor, make sure it is in the body, never within its initializer list. Always clean up such unmanaged resource acquisition in local try block handlers within the constructor or destructor body, never in constructor or destructor function try block handlers.
push_backstd::rel_op operatorsPrefer a checked STL implementation.
Some STL usage mistakes are distressingly common and difficult to detect; however, a checked STL implementation can help detect them.
See Item 83 of [Sutter2005a].
Choose an appropriate container when you have a compelling reason; otherwise use vector by default.
Use vector (and string::c_str) to exchange data with non-C++ APIs.
See Item 76 & 78 of [Sutter2005a].
Store objects of value in containers. Containers assume they contain value-like types, including value types (held directly), smart pointers, and iterators.
See Item 79 of [Sutter2005a].
push_backPrefer push_back over other ways of expanding a sequence.
See Item 80 of [Sutter2005a].
Prefer range operations over single-element operations.
See Item 81 of [Sutter2005a].
Use the accepted idioms to really shrink capacity and really erase elements.
container<T>(c).swap(c);container<T>().swap(c);c.erase(remove(c.begin(), c.end(), value), c.end());remove or remove_if member when available.See Item 82 of [Sutter2005a].
Prefer using algorithm calls over handwritten loops.
Algorithm calls can be more expressive and maintainable, less error-prone and as efficient as handwritten loops.
Consider trying the Boost Lambda library, which automates the task of writing function objects.
See Item 84 of [Sutter2005a].
Choose an appropriate search algorithm using the inside cover of [Meyers2001].
See Item 85 of [Sutter2005a].
Choose an appropriate sort algorithm.
See Item 86 of [Sutter2005a].
std::rel_op operatorsThe std::rel_op operators (in utility) are of limited usefulness.
The std::rel_op operators break the iterator operators (and all similar operators).
(They were apparently a mistake.)
If you insist on using them, you will have trouble.
Avoid using the std::rel_op operators.
It is reasonable to assume that a junior programmer understands every feature of the used programming language. If they do not, they can always look it up or ask someone.
Any programmer that does not investigate language features they do not understand should be dismissed. If they are unwilling to take the effort to learn about the effective use of the tools of their trade, they will never become an effective craftsman.
Design modules so that they are as orthogonal (independent) of each other as possible.
Always endeavor to give each entity—variable, function, class, namespace, module, library—a single, well defined responsibility. Prefer encapsulation. Separate concerns.
Modules, classes, and functions can be more easily reused without dragging along otherwise unnecessary baggage.
See Item 5 of [Sutter2005a].
Experienced programmers understand how to strike the right balance between writing special-purpose code that solves only the immediate problem and writing a grandiose general framework to solve what should be a simple problem.
See Item 7 of [Sutter2005a].
A public virtual function inherently has two different and competing responsibilities, aimed at two different and competing audiences:
In base classes with high cost of change (particularly those in libraries and frameworks): Prefer to make public functions nonvirtual. Prefer to make virtual functions private (or protected if derived classes need to be able to call the base versions). This is the Nonvirtual Interface pattern.
By separating public functions from virtual functions:
See Item 39 of [Sutter2005a].
For widely used classes, prefer to use the compiler-firewall idiom (aka Pimpl Idiom) to hide implementation details.
Use an opaque pointer (a pointer to a declared, but as yet undefined, class) declared similar to struct XxxxImpl; XxxxImpl* pimpl; to store private members (including both state variables and member functions).
Changes can be made to implementation details without forcing a recompilation of client code. This also reduces code interdependencies.
See Item 43 of [Sutter2005a].
Provide unit test applications for every non-user-interface class and/or module. A Unit test suite should have 100% path coverage.
Although the goal of unit testing is 100% path coverage, on rare occasions no input to a program can cause a particular path to be executed. In such an instance, an explanatory assertion on the unexecuted line should make this clear (so maintainers later running the unit test can learn this line is not expected to be executed).
Clients can rely on the assumption that your class and/or module has been thoroughly tested.
For projects used in highly vertical domains, deliverables should contain a project (or class) glossary for domain specific terms.
Client programmers can lookup and properly understand the terms used in the project (or class).
Deliverables should be as self-documenting as possible. The careful choosing of descriptive, unambiguous identifiers can greatly enhance self-documentation.
Extraneous documentation is notorious for being out of date with what is actually happening. If source code is self-documented, as the code changes, so does the documentation.
Instead of leaving things implicit, express them explicitly.
Which files must be #included for a given source file to compile.
Although being explicit may take a few extra keystrokes, it reduces the potential for confusion, which is far more important.
Source code should take advantage of a language’s built in type checking wherever feasible.
If a passed in object is compiler acceptable, both client and implementation know what can be done because the object is of an explicit type.
Prefer the C++ style casts [e.g., static_cast<T>(x) or const_cast<T>(x), et.al.] over C style casts [e.g., (T)x].
However, prefer using mutable over const_cast<>.
C++ style casts make the type of a cast more explicit, and it is easier to search for casts of a particular type. (Often times a compiler warning can be enabled to flag uses of the older, C style casts.)
See Item 95 of [Sutter2005a].
reinterpret_cast is not guaranteed to reinterpret the bits of one type as those of another (or guaranteed to do anything else in particular).
Avoid using reinterpret_cast.
If you must cast between unrelated pointer types, prefer casting via void* instead of using reinterpret_cast directly.
Instead of:
T1* p1 = ...
T2* p2 = reinterpret_cast<t2*>(p1);
write
T1* p1 = ...
void* pV = p1;
T2* p2 = static_cast<t2*>(pV);
See Item 92 of [Sutter2005a].
Pointers to dynamic objects do not static_cast.
Prefer to re-factor, redesign or use dynamic_cast.
Avoid using static_cast on pointers.
Q: How does this maxim square with the previous one?
Although dynamic_cast is slightly less efficient, it also detects illegal casting (and this minor efficiency difference can be considered premature optimization).
Q: Can dynamic_cast be called on objects of types that do not have a virtual function table?
See Item 93 of [Sutter2005a].
C++ does not force a programmer to provide an initializer list for a constructor. Neither does it force us to put an initializer list in the order in which the members will actually be initialized.
Every constructor should contain an initializer list that contains initializers for, at a minimum:
Initializers for built-in types are also recommended, however, unlike the above, there is no duplication of effort if these are put off until the body of the constructor.
Unmanaged resource acquisition in a constructor.
The C++ language mandates that the compiler must construct non-built-in types in the initializer list.
A programmer’s failure to explicitly construct an object of a non-built-in type in an initializer list causes the compiler to implicitly construct the object (using the default constructor).
Then, when you later assign a value to it in the constructor’s body, the object’s operator= is called.
Not only does this leave the phases of object construction implicit, it is also a needless, inefficient duplication of effort.
Regardless of the order initializers are shown in an initializer list, the language always initializes base classes and members in the order they are declared within the class definition. Because initializers can sometimes depend upon each other, failing to display the initializer list in the declared order often leads to subtle bugs. Displaying initializers in the correct order also allows those viewing the list to view the dependencies, thereby reducing the opportunity for unintentional errors.
This is also a requirement for some class template constructors, especially when the templatized parameter is a built-in type. (See Section 5.5 of [Vandevoorde2003] for more on this.)
See Item 47 & 48 of [Sutter2005a].
The designated initializer of a class in Objective-C follows a pattern:
- (id)initWithObject:(SomeType*)object
{
NSParameterAssert(object != nil);
NSAssert([object isValid], @"Expected validated object");
self = [super init]; // Send message to any appropriate initializer of the base class.
if (self != nil)
{
// Members asserted, assigned, or alloced & inited (in declaration order), thereby documenting that their initial state has been properly considered (and not presumed).
NSAssert(mNumThings == 0, @"Expected init to zero");
NSAssert(NSEqualRects(mMemberRect, NSZeroRect), @"Expected init to zero");
NSAssert(mMemberObj1 == nil, @"Expected init to zero");
mMemberObj2 = object;
mMemberObj3 = [[SomeType alloc] init];
mMemberObj4 = [[SomeOtherType alloc] init];
// If any member allocation failed... (we verify in alloced order)
if (mMemberObj3 == nil
|| mMemberObj4 == nil)
{
[self autorelease]; // -dealloc will release already alloced members
self = nil;
}
}
// If nothing failed...
if (self != nil)
{
// Here you do those things that cannot fail. For example:
// - registering for notifications.
}
NSParameterAssert(self == nil || self != nil);
// The above line is not a nonsensical statement as some might imagine. It is an executable comment that states this method may return nil or not, and thereby making plain that it is the responsibility of the caller to ensure what is returned is non-nil before using it.
return self;
}
Non-designated initializers of a class call the designated initializer, either directly or indirectly.
- (id)initNonDesignatedInitializer
{
// Get arguments required by DesignatedInitializer
SomeType* obj = [SomeType defaultObject];
// Use designated initializer to init the object
self = [self initWithObject:obj];
NSAssert(self == nil || self != nil);
return self;
}
When the above two maixims are followed:
“…the problem of proving that a given algorithm is valid evidently consists mostly of inventing the right assertions to put in the flow chart [or code].…The above principle for proving algorithms has another aspect which is perhaps even more important: it mirrors the way we “understand” an algorithm.…It is the contention of the author that we really understand why an algorithm is valid only when we reach the point that our minds have implicitly filled in all the assertions…. This point of view has important psychological consequences for the proper communication of algorithms from one man to another (or from one man to himself, when he looks over his own algorithms several months later)….”
—[Knuth1973], p. 16
Liberally use assert()—or an equivalent, like NSAssert()—to document assumptions internal to a module (i.e., where the caller and callee are maintained by the same person or team).
Every assertion should be thought of as a comment that happens to be executed (while debugging) to verify that its statement is, in fact, true.
Documenting preconditions, postconditions and invariants.
Instead of providing a comment saying something like: “At this point X should be true”, provide the comment in the form of an assertion that fires when X is not true.
There are errors that you know might happen.
For everything else that should not (and it is a programmer’s fault if it does) there is assert() (or an equivalent).
The debugging version of the program will catch those instances when, quite unexpectedly, the assumption is incorrect.
Never write expressions with side effects in assert() statements (or other debugging macros) whose contents will vanish from some configurations.
Prefer assert(!"informational message") over assert(false) and consider adding && "Informational message" to more complex assertions.
(Also consider our proclaim_() and avow_() debugging macros and their printf-like counterparts as well as our CompileTimeAssert_() debugging macro.)
See Item 68 of [Sutter2005a].
Certain statements in all languages evaluate Boolean conditions (e.g., if(), while(), etc.).
Phrase statements that evaluate Boolean conditions as Boolean expressions.
Prefer if (pointer != 0) over an implied comparison against zero, such as if (pointer).
By doing so, the condition is explicit and reads more like English. With a moderately proficient compiler there is no performance penalty.
C++’s built-in bool type can do some things that homegrown Boolean types (whether based on type char, int or whatever) cannot.
That is why it was added to the C++ language.
Prefer bool (or in Objective-C: BOOL) over homegrown Boolean types.
Numeric literals (other than the ubiquitous 1 or 0) should only appear in static constants or enumerator declarations; i.e., avoid “magic numbers.”
This centralizes specification of such numbers and eliminates the possibility of multiple definitions for what should amount to the same number. Names add information. Even if you think your number will be used in only one place, magic numbers by themselves are not self-documenting, nor will others easily understand their raison d’être.
See Item 17 of [Sutter2005a].
new & delete are staticAlways explicitly declare operator new() and operator delete() as static functions.
Regardless of how they are declared, the compiler will never make them non-static member functions.
Others should easily understand deliverables (i.e., they should be intuitive to a junior programmer).
Understanding leads to correctness.
See Item 6 of [Sutter2005a].
typdefPrefer readability. Avoid writing terse code (i.e., code that is brief, but difficult to understand and maintain). Eschew superfluous obfuscation.
Small classes are easier to write, get right, test, and use. They are also more likely to be usable in a variety of situations. Prefer small classes that embody simple concepts instead of kitchen sink classes that try to implement many and/or complex concepts.
See Item 33 of [Sutter2005a].
Try to avoid assignments inside Boolean conditions.
Instead of writing this:
if ((foo = (char*) malloc(sizeof(char*)) == 0)
{
fatal (“virtual memory exhausted”);
}
write this:
foo = (char*) malloc(sizeof(char*));
if (foo == 0)
{
fatal (“virtual memory exhausted”);
}
There is no loss of efficiency and it is easier to read. It is also easier to see what is happening when stepping through the code with a debugger.
Even though the language allows it—one might even say encourages it—, avoid sending more than one message on a line.
Instead of this:
NSWindow* window = [[self windowController] window];
Prefer this:
NSWindowController* windowController = [self windowController];
NSAssert(windowController != nil, @"Expected valid windowController");
NSWindow* window = [windowController window];
Allocation and initialization, as well as an autorelease, often occur together.
NSWindow* window = [[[NSWindow alloc] init] autorelease];
The second form not only validates the returned windowController before using it, more importantly, it is more debugger friendly. When stepping through code, one thing is accomplished per line, and it is therefore easier to step into the appropriate method call. There is no advantage to the more compact form, except its compactness, which is less important than ease of debugging.
typdefUse typedefs to improve:
Avoid preprocessor macros created with #define.
Macros usually make code more difficult to understand and, therefore, more troublesome to maintain.
Exceptions to this maxim are:
#include guards;assert() does);#pragmas used to disable known innocuous warnings (but such #pragmas should typically be inside “conditional compilation for portability” guards to prevent warnings from compilers that do not understand them).Every #endif should have a comment—except in the case of short conditionals (just a few lines) that are not nested—and the comment should state the condition of the conditional that is ending, including its sense.
Every #else should also have a comment describing both the condition and sense of the code that follows.
#ifdef qFoo
//...
#else /* ndef qFoo */
//...
#endif /* ndef qFoo */
#ifdef qBar
//...
#endif /* def qBar */
Do not expose internal information from an entity that provides an abstraction.
This minimizes dependancies, localizes changes and strengthens invariants.
See Items 11 & 42 of [Sutter2005a].
Make data members private, except in behaviorless aggregates (C-style structs).
See Item 41 of [Sutter2005a].
Identifiers should be descriptive, of unambiguous meaning and self-documenting.
An English dictionary is an indispensable tool when it comes to providing descriptive identifiers. (It is also handy if you encounter an identifier whose meaning is even slightly unclear. ;-)
The C++ standard reserves some leading-underscore and double underscore identifiers for the implementation of the language. The actual rules for this are complex and hard to remember, therefore…
In identifiers, avoid leading underscores and double underscores entirely.
Avoids accidental and unintentional name overloading and hiding.
Have every identifier representative of the highest level of abstraction commensurate with its context.
Understanding leads to correctness.
See also Item 63 & 67 of [Sutter2005a].
Pointers are a unique form of object identifier. They can either refer to a valid object or they can refer to no object. (Unfortunately, in poorly written programs, they can also refer to a random area of memory.) Other forms of object identifiers (such as those identifying values, or C++ references) must always refer to their object, i.e., they always refer to one particular place in memory (or a register) reserved for their particular object.
Pointers should always either:
A pointer that points to random memory is always an invalid pointer; i.e., a bug waiting to happen. In the same way that objects of other types should always be initialized to a valid state, a pointer should always be initialized with the address of a valid object or with zero (aka NULL or nil).
Information is passed between different pieces of code using one of five mechanisms:
Avoid global objects. As a client, predicting side effects is virtually impossible.
Predictability leads to correctness; unpredictability leads to errors.
See Item 10 of [Sutter2005a].
Treat similar to global objects, although class static variables are to be preferred over global objects because of their more limited scope. In C++, prefer to use anonymous namespaces to create file-scope variables.
Class member variables should really only be used for maintaining an object’s state; they should not really be used to pass information to a function that will be called later. Of course, there are rare situations where this cannot be avoided.
Objects have a minimal footprint.
Within this section, the terms In, Out & IO have special, mutually exclusive meanings. They are:
A parameter delineated In is a parameter whose argument will only be examined by a function; the function will never modify the passed in argument. Think of In as a “read-only” designation for the passed in argument.
A parameter delineated Out is a parameter whose argument may be modified by a function; however, the function will never examine the passed in argument. Think of Out as a “write only” designation for the passed in argument.
A parameter delineated IO is a parameter whose argument may be examined by a function and may also be modified by a function. Think of IO as a “read/write” designation for the passed in argument.
In C++, a function declaration’s parameter list determines how an argument is passed in and it therefore implicitly informs clients of how their passed in argument(s) will be used and/or modified.
When an argument is passed according to the method shown in the left column of the following table (an example of which is shown in the second column), clients can rely on the meaning shown in the third column.
| Passed | Example | In, Out or IO | Notes |
|---|---|---|---|
| By non-const “this” pointer | MemberFn(/*…*/); | Can mean In, Out or IO, but should mean Out or IO | Should never mean In. Redeclare to ‘by const “this” pointer’ when you mean In |
| By const “this” pointer | MemberFn(/*…*/) const; | Always means In | |
| By non-const value | Fn(char); | Always means In | Typically used with built-in types |
| By const value | Fn(const char); | Always means In | Rarely used in practice |
| By reference to non-const | Fn(char&); | Can mean In, Out or IO | Should be very rare. |
| By reference to const | Fn(const char&); | Always means In | |
| By pointer to non-const | Fn(char*); | Can mean In, Out or IO | Preferred for Out and IO. |
| By pointer to const | Fn(const char*); | Always means In | Prefer by reference to const unless the pointer is optional |
Predictability and understanding leads to correctness.
See also Item 25 of [Sutter2005a].
Non-static class member functions have an implied “this” parameter. Static member functions do not.
Member functions that do not refer to member variables should be declared static.
static void Fn(void);
If clients will not need to access such a function—i.e., if it is used by a class’s implementation only—such a function should not be declared within the class definition; instead make it a free standing function in an unnamed namespace in the implementation file. (This keeps implementation details out of a class’s interface.)
Member functions that only examine (i.e., read) member variables should be declared const.
void Fn(void) const;
Member functions that modify member variables should be declared non-const.
void Fn(void);
Passing an argument “By value” always means In.
Passing an object by value means, by definition, call the copy constructor.
Only built-in types (and very small user defined types) should be passed into functions by value. Prefer passing “By reference to const” for user defined types.
Avoid const pass-by-value parameters in function declarations. (However, making the parameter const in the same function’s definition—if it will not be modified—may be useful.)
There is no benefit to declaring a parameter passed by value as const. In fact, to the compiler, the function’s signature is the same whether you include const before the parameter or not, which is why you can define it differently than it is declared.
Passing an argument “By reference to const” always means In.
It is an established C/C++ industry standard (cf. section 5.5 of [Stroustrup1997]) that passing a value by pointer implies that the value may be changed; therefore:
Function writers should only very rarely declare parameters as pass “By reference to non-const”.
Why? The calling syntax for a function that takes an argument “By reference” is identical to the calling syntax for a function that takes an argument “By value.” Therefore, receiving an argument “By reference to non-const” allows a function writer to modify the argument without supplying a hint, at the call location, that such a modification might take place.
An additional reason is that a reference to non-const cannot be bound to a temporary object; therefore functions that take their parameters by reference to non-const cannot accept explicit constructor invocations or temporaries resulting from expressions.
The only known exceptions to this practice are operator overloading such as operator<< and operator>> for formatted stream activities.
This does not tend to be a problem because everyone intuitively knows that a stream is being changed by these calls; the implied meaning of “cout << 5” is write to (and therefore change) the output stream.
In those rare instances where arguments are passed “By reference to non-const,” good engineering practice dictates that function writers make plain at the function’s declaration (via comments or identifier naming conventions) exactly how the object being referred to will be used (i.e., Out or IO).
Because non-const pointers can be used for In, Out or IO, good engineering practice dictates that function writers make plain at a function’s declaration (via comments or identifier naming conventions) how the object being pointed to will be used.
It is an established C/C++ industry standard (cf. section 5.5 of [Stroustrup1997]) that passing a value by pointer implies that the value may be changed; therefore:
Passing arguments by pointer to const is discouraged (although when it happens, it always means In).
Because pointers are unique, good engineering practice dictates that function writers make plain at a function’s declaration (via type) ownership issues and (via comments or identifier naming conventions) whether a pointer parameter is required or optional (i.e., whether the function accepts and properly works with a pointer value of zero).
In C++, functions can directly return an object. (Of course, objects can also be indirectly returned via a function’s parameter list.)
Returning an object by value means, by definition, call the copy constructor.
Copy construction for non-built-in types is typically expensive so returning an object by value should be avoided, if possible, unless the object is of one of the built-in types (which are copied quickly).
Some functions have no choice but to return an object by value (e.g., operator[]).
If returning an object by value cannot be avoided, attempt to structure the implementation so that the compiler can perform the “return value optimization.”
When using return-by-value for non-built-in types, prefer returning a const value.
This assists client code by making sure the compiler emits an error if the caller tries to modify the temporary.
Returning an object by reference is the preferred means by which an object can be directly returned from a function.
Local automatic objects have their destructor called when they pass out of scope.
Attempting to refer to local automatic objects (whether by pointer or by reference) after they have passed out of scope is always an error.
Because pointers are unique, good engineering practice dictates that functions should only return objects by pointer when the function may not have an object to return. In other words, clients must always determine whether a returned pointer is non-nil.
Deliverables should be well commented in those inevitable complex areas.
Understanding leads to correctness.
Write for efficiency only when and where necessary.
The quicker we find things, the more time we can spend on correctness, completeness and runtime efficiency.
Source code files should be arranged so common pieces of information are easily located.
In English we read left to right and top to bottom. Speakers of English tend to look for important information at the top or beginning of a file.
Items of more general interest should be placed towards the top of a file.
Variables whose declarations may not be readily visible to a human reader at their point of use should contain a hint as to their declaration’s location.
Prefixing ‘g’ to global variables, ‘s’ to class static variables or ‘m’ to member variables gives a hint to clients of how to go about finding their declarations.
Deliverables should avoid duplication of information.
With identical information in more than one place, it is easy to get the information in these locations out of synchronization. When that happens, clients cannot know which is the correct information.
Source code should compile efficiently (both in actual compile time and when considering the effort required to “put the pieces together”).
When even minor corrections do not take an inordinate amount of time to build, corrections are more likely to be made instead of being “put off.”
#pragma onceJust inside a .h file’s #include guards, at the top, provide these three lines:
#if defined(PRAGMA_ONCE) && PRAGMA_ONCE
#pragma once
#endif
If a compiler supports it, #pragma once is faster than #include guards because the file does not have to be loaded and parsed each time in order to prevent multiple inclusions.
Compile times are greatly influenced by how compilers determine those files affected by any given change.
Making changes to any .h file forces the compiler to recompile every file that #includes (or #imports) the changed .h file, either directly or indirectly.
Within .h files, do not #include (or #import) a header when a forward declaration will suffice.
Because interface files contain documentation on how their contents are used, we want minor (otherwise insignificant) changes to documentation to only force recompilation of as few files as necessary. This maxim can significantly reduce compile times resulting from a modified .h file.
#include <iostream>Because of the C++ standard’s allowance for various implementation defined dependencies and enhancements, client programmers are not allowed to forward declare anything that lives in namespace std.
However, the makers of the C++ standard understood the value of preferring forward declarations, so they mandated that library providers supply the file iosfwd.
Whenever a forward declaration of one of the stream classes will suffice, #include <iosfwd>.
iostream will only need to be included in order to access the actual standard streams (e.g., cout).
General files tend to have a broader clientele than files covering a more specific, limited topic. The more “common” or general a file is, the more likely it is to have already been included by some other file.
By deferring inclusion of more general files until after the more specific, the more general files may not even need to be explicitly included.
One of the more specific files may have already included an otherwise necessary general file. (This is one exception to the “be explicit” maxim. Explicitly including every file of a #include hierarchy would be a significant maintenance hassle.)
To make a #include list easier to decipher, break it into groups (by library, etc.) In order to reduce the size of #include lists, include less general (i.e., most unique) libraries first and more general libraries later. The order within a given library’s listing should be alphabetical to make it easier to find a given file.
#include “thisFile.h” // Within an implementation file only:
// An implementation’s .h file should be first and in a group by itself
#include “SomeOtherProjectFile.h” // Project specific files and files
#include “SomeProjectFile.h” // not likely to be owned by a client are
// next
#include <iosfwd> // Readily available library files, such as
// Cocoa, the STL, PowerPlant, UniversalInterfaces, etc.
#include <memory> // For example, the language's library is more general than
// the STL; place its files after the STLs'
The items in this section should not be viewed as so-called “premature optimizations.” They are intended to engender habits that avoid “gratuitous pessimizations.”
op= over opT v(a) over T v = aAvoid defining constructors and destructors inline; doing so contributes to code bloat.
Exceptions should only be made for constructors/destructors of classes that have:
Because of the complexity of constructors and destructors, and because compilers typically do much of their behind the scenes work as part of them, only in the rare exception mentioned above are constructors and destructors sufficiently small to profit through inlining.
Minimize the number of places where temporary objects are used.
Construction of temporary objects can wreak havoc on code’s efficiency.
Passing non-built-in types by value causes a temporary to be created, and so should be avoided if possible.
explicitConstructors that can be called with one argument should be declared explicit to prevent unintentional construction of temporary objects due to implicit type conversions.
An exception should probably be made for the copy constructor. Although requiring explicit copy constructor calls would help prevent unintentional pass-by-value arguments, it also would make other useful constructs impossible.
Avoid actually declaring exception specifications [e.g., void SomeFn(void) throw()].
It is still reasonable to provide such a guarantee to a client but document it as a comment instead of as an actual exception specification [e.g., void SomeFn(void) // throw()].
A non-inline function is the one place a “throws nothing” exception-specification may have some benefit with some compilers.
Exception specifications are notoriously inefficient with today’s compilers. (Consult Boost’s rationale for more on this topic.)
See Item 75 of [Sutter2005a].
Objects should be declared at the point of their need, and not in advance of that.
Because variables are to be initialized when they are declared, to declare an object causes a constructor to be called or it to be alloced and initiallized. If that construction can be put off (or is not needed at all) for some code paths, then the resulting object code will run faster. Of course moving some declarations outside a loop can also be more efficient.
Also, even in languages like C and Objective-C where declaring an object does not cause immediate construction—although objects should still be initialized when they are declared—, delaying declarations allows an optimizing compiler to better overlap register usage.
See Item 18 of [Sutter2005a].
Initialize objects at their point of declaration instead of later.
Initialization at the point of declaration [e.g., Type var(initializer)] requires one constructor call; whereas, first declaring an object’s type and then initializing the object (e.g., Type var; var = initializer) results in a (default) construction call and an assignment call.
See Item 19 of [Sutter2005a].
One of the tenets of Structured Programming is having a Single Entry/Single Exit for every block. This is generally a good policy. It improves readability and should be adhered to when other engineering considerations do not override it.
With the following example code, some compilers may generate code that calls autoInstance’s destructor in two places, once for each return statement.
int SomeFn1(void)
{
CSomeClass autoInstance(someInitializer);
if (SomeTest())
{
return SomeOtherFn(someInstance);
}
SomeThirdFn();
return 0;
}
However, with the following example code, the code calling autoInstance’s destructor is only generated once, immediately before the return.
int SomeFn2(void)
{
int someInt = 0;
CSomeClass autoInstance(someInitializer);
if (SomeTest())
{
someInt = SomeOtherFn(someInstance);
}
SomeThirdFn();
return someInt;
}
Avoid multiple return statements in functions, especially when they construct/destruct automatic objects. Of course, this must be balanced with the ability to capitalize on the return value optimization.
With regard to loops, precompute values that will not change as a result of the loop.
Calls to functions (such as the standard library function end()) take time and, if the function result is not going to change during a loop (because the container is not going to change), it can be called once instead of every pass through the loop.
Unnecessarily executing code negatively impacts the “snappiness” of an application.
Postincrement has to do all the same work as preincrement, but in addition it also has to construct and return another object containing the original value.
Only use the postincrement operator (j++) if you are actually going to use the original value.
Otherwise, prefer preincrement (++j).
Unnecessarily executing code negatively impacts the “snappiness” of an application.
(Using postincrement as an idiomatic part of for statements (e.g. for ( ; ; x++)) is actually a remnant left over from the when C was first introduced.
We have learned a few things since then.
Break the habit and move on!)
op= over opSee Implement operator op() in terms of operator op=().
Prefer writing a op= b; instead of a = a op b; (where op stands for any operator).
Multiple op= statements are better than a chained compound statement of operators.
It is clearer and more efficient.
T v(a) over T v = aPrefer using the form “T v(a);” instead of “T v = a;” where possible.
The former usually works wherever the latter works, and has other advantages—e.g., it can take multiple parameters. The latter may also force construction of an otherwise unnecessary temporary.
if blocksWhen both options of a given conditional require a coded response, how does a programmer decide the phrasing of the if statement?
Does he use if (isTrue) or if (!isTrue)?
As a general rule, the first block of an if statement—the “is true” part—requires an assembly language statement to jump over the second part—the “is false” part.
Conversely, execution of the second part typically “just falls off the end” and continues with the code following the second part.
Phrase the condition of an if statement such that the code responding to the slowest (or most frequent) condition is in the block following the else clause.
The fastest block (or rarely executed block) bears the burden of the extra assembly language instruction. (Granted, the execution time of the extra instruction is trivial, so there is no need to waste a lot of time with this. Don’t “prematurely optimize”, but this provides a reasonable rule for making an otherwise arbitrary decision.)
A classic example of this might be error checking.
Only in rare instances will the error condition be encounterd.
Therefore, even though the “normal” condition may have far less work to do than when an error occurs, because the “normal” condition is so frequent, it should still follow the else clause.
Coincidentally, following this general maxim also frequently places the smallest—by code size—block before the else making it easier to keep the condition in mind when you get to the second part of the if statement.
It should go without saying that resulting footprints (RAM, as well as disk) should be minimal.
This is the end of our Reliable Engineering Practices document.
As a reminder, now that you have laid a solid foundation, you may wish to consider reading our Style Guidelines.