Dr. Dobb's Programmer's Bookshelf Newsletter

Book Excerpt

The new book C++ Coding Standards, by Herb Sutter and Andrei Alexandrescu, delivers a valuable set of tried-and-true rules, guidelines, and best practices condensed into 101 concise one- and two-page Items. But this book is something more: It also acts as an index into the world's C++ literature because each Item includes copious references that, in all, cite nearly 100 different top books and articles-from Brooks' classic The Mythical Man-Month to Vandevoorde and Josuttis' cutting-edge C++ Templates to the authors' own previous books-and distill the scattered advice and guidelines into one authoritative handbook.

For this excerpt, the authors have selected four Items drawn from various parts of the book: The first is the book's very first Item drawn from the opening section on Organizational and Policy Issues, the next two are from the section on Design Style, and the fourth is from the section on Templates and Genericity. These deliberately lean toward the higher-level, farther-reaching Items to give a broader flavor for the book's approach, and fewer code examples to flow better into a narrower magazine layout. The book's other sections cover: Coding Style; Functions and Operators; Class Design and Inheritance; Construction and Destruction, Copying and Assignment; Namespaces and Modules; Error Handing and Exceptions; STL: Containers; STL: Algorithms; and Type Safety.

Get into a rut early: Do the same process the same way. Accumulate idioms.
Standardize. The only difference(!) between Shakespeare and you was the size of his idiom list-not the size of his vocabulary.

                                                                  - Alan Perlis [emphasis ours]

The best thing about standards is that there are so many to choose from.

                                                                  - Variously attributed

Don't sweat the small stuff.
(Or: Know what not to standardize.)

Summary

Don't enforce matters of personal taste. Don't enforce obsolete practices.

Discussion

Issues that are really just personal taste and don't affect correctness or readability don't belong in a coding standard. Any professional programmer can easily read and write code that is formatted a little differently than they're used to.

Do use consistent formatting within each source file, because it's jarring to jump around between several styles in the same piece of code. But don't try to enforce consistent formatting across a whole project or company.

Here are several common issues where the important thing is not to set a rule but just to be consistent with the style already in use within the file you're maintaining:

     Don't specify how much to indent, but do indent to show structure: Use any number of spaces you like to indent, but be consistent within at least each file.

     Don't enforce a specific line length, but do keep line lengths readable: Use any length of line you like, but don't be excessive. Studies show that up to 10-word text widths are optimal for eye tracking.

     Don't overlegislate naming, but do use a consistent naming convention: There are only two must-dos: a) never use "underhanded names, ones that begin with an underscore or that contain a double underscore; and b) always use ONLY_UPPERCASE_NAMES for macros and never think about writing a macro that is a common word or abbreviation (including common template parameters, such as T and U; writing #define T anything is extremely disruptive). Otherwise, do use consistent and meaningful names and follow a file's or module's convention. (If you can't decide on your own naming convention, try this one: Name classes, functions and enums LikeThis; name variables likeThis; name private member variables likeThis_; and name macros LIKE_THIS.)

      Don't prescribe commenting styles (except where tools extract certain styles into documentation), but do write useful comments: Write code instead of comments where possible (e.g., see Item 16). Don't write comments that repeat the code; they get out of sync. Do write illuminating comments that explain approach and rationale.

Finally, don't try to enforce antiquated rules (see Examples 3 and 4) even if they once appeared in older coding standards.

Examples

Example 1: Brace placement. There is no readability difference among:

void using_k_and_r_style() {

   // ...

}

void putting_each_brace_on_its_own_line()

{

   // ...

}

void or_putting_each_brace_on_its_own_line_indented()

   {

   // ...

   }

Any professional programmer can easily read and write any of these styles without hardship. But do be consistent: Don't just place braces randomly or in a way that obscures scope nesting, and try to follow the style already in use in each file. In this book, our brace placement choices are motivated by maximizing readability within our editorial constraints.

Example 2: Spaces vs. tabs. Some teams legitimately choose to ban tabs (e.g., [BoostLRG]), on the grounds that tabs vary from editor to editor and, when misused, turn indenting into outdenting and nondenting. Other equally respectable teams legitimately allow tabs, adopting disciplines to avoid their potential drawbacks. Just be consistent: If you do allow tabs, ensure it is never at the cost of code clarity and readability as team members maintain each other's code (see Item 6). If you don't allow tabs, allow editors to convert spaces to tabs when reading in a source file so that the user can work with tabs while in the editor, but ensure they convert the tabs back to spaces when writing the file back out.

Example 3: Hungarian notation. Notations that incorporate type information in variable names have mixed utility in type-unsafe languages (notably C), are possible but have no benefits (only drawbacks) in object-oriented languages, and are impossible in generic programming. Therefore no C++ coding standard should require Hungarian notation, though a C++ coding standard might legitimately choose to ban it.

Example 4: Single entry, single exit ("SESE). Historically, some coding standards have required that each function have exactly one exit, meaning one return statement. Such a requirement is obsolete in languages that support exceptions and destructors, where functions typically have numerous implicit exits. Instead, follow standards like Item 5 that directly promote simpler and shorter functions that are inherently easier to understand and to make error-safe.

References

[BoostLRG]; [Brooks95] 12 ; [Constantine95] 29 ; [Keffer95] p. 1 ; [Kernighan99] 1.1, 1.3, 1.6-7 ; [Lakos96] pp. 34-38, 91-93 ; [McConnell93] 9, 19 ; [Stroustrup94] 4.2-3 ; [Stroustrup00] 4.9.3, 6.4, 7.8, C.1 ; [Sutter00] 6, 20 ; [SuttHysl01]

Clarity, simplicity, and correctness come first.

Summary

Prefer simple and clear designs and code over complex alternatives. Avoid the "dusty corners of the language. Use the simplest techniques that are effective.

Discussion

It's hard to overstate the value of clear designs and lucid code. The person who has to maintain your code will thank you for making it understandable-and often that maintainer will be your future self, looking at the code six months later and trying to remember what you were thinking. Hence such coding and design wisdom as:

Write programs for people first, computers second. -Steve McConnell

The cheapest, fastest and most reliable components of a computer system are those that aren't there. -Gordon Bell

Those missing components are also the most accurate (they never make mistakes), the most secure (they can't be broken into), and the easiest to design, document, test and maintain. The importance of a simple design can't be overemphasized.
-Jon Bentley

Many of the Items in this book naturally lead to designs and code that are easy to change, and clarity is the most desirable quality of easy-to-maintain, easy-to-refactor programs. What you can't comprehend, you can't change with confidence.

Probably the most common tension in this area is between code clarity and code optimization (see Items 7, 8, and 9). When—not if—you face the temptation to preoptimize for performance and thereby pessimize clarity, recall Item 8's point: It is far, far easier to make a correct program fast than it is to make a fast program correct.

Examples

Example 1: Avoid gratuitous/clever operator overloading. One needlessly weird GUI library had users write w + c; to add a child control c to a widget w. (See Item 26.)

Example 2: Prefer using named variables, not temporaries, as constructor parameters. This avoids possible declaration ambiguities. It also often makes the purpose of your code clearer and thus is easier to maintain. It's also often safer (see Items 13 and 31).

References

[Bentley00] 4 ; [Cargill92] pp. 91-93 ; [Cline99] 3.05-06 ; [Constantine95] 29 ; [Keffer95] p. 17 ; [Lakos96] pp. 584-586, 680-681 ; [McConnell93] ; [Meyers01] 47 ; [Stroustrup00] 1.7, 2.1, 6.2.3, 23.4.2, 23.4.3.2 ; [Sutter00] 40-41, 46 ; [Sutter04] 29

Use explicit RAII and smart pointers.
Ensure resources are owned by objects.

Summary

C++'s "resource acquisition is initialization (RAII) idiom is a powerful tool for correct resource handling. RAII allows the compiler to provide strong and automated guarantees that in other languages require fragile hand-coded idioms.

When allocating a raw resource, always immediately pass it to an owning object. Never allocate more than one resource in a single statement.

Discussion

C++'s language-enforced constructor/destructor symmetry mirrors the symmetry inherent in resource acquire/release function pairs such as fopen/fclose, lock/unlock, and new/delete. This makes a stack-based (or reference-counted) object with a resource-acquiring constructor and a resource-releasing destructor an excellent tool for automating resource management and cleanup.

The automation is easy to implement, elegant, low-cost, and inherently error-safe. If you choose not to use it, you are choosing the nontrivial and attention-intensive task of pairing the calls correctly by hand, including in the presence of branched control flows and exceptions. Such C-style reliance on micromanaging resource deallocation is unacceptable when C++ provides direct automation via easy-to-use RAII.

Whenever you deal with a resource that needs paired acquire/release function calls, encapsulate that resource in an object that enforces pairing for you and performs the resource release in its destructor. For example, instead of calling a pair of OpenPort/ClosePort nonmember functions directly, consider:

class Port {

public:

  Port( const string& destination );         // call OpenPort

  ~Port();                                     // call ClosePort

  // ... ports can't usually be cloned, so disable copying and assignment ...

};

void DoSomething() {

  Port port1( "server1:80 );

  // ...

} // can't forget to close port1; it's closed automatically at the end of the scope

shared_ptr<Port> port2;             // port2 is closed automatically when the

                                                      // last shared_ptr referring to it goes away

You can also use libraries that implement the pattern for you (see [Alexandrescu00c]).

When implementing RAII, beware of copy construction and assignment. If you choose to support them, implement the copy constructor to duplicate the resource or track the number of uses with a technique such as reference counting (the compiler-generated copy constructor almost certainly won't be correct), and

have the assignment operator do the same and ensure that it frees its originally held resource if necessary. One classic oversight is to free the old resource before making sure the new resource is properly duplicated and ready for use (see Item 71). Otherwise, explicitly disable them by making them private and undefined (see Item 56).

Make sure that all resources are owned by objects. To this end, perform every explicit resource allocation (e.g., new) in its own statement which immediately gives the allocated resource to a manager object (e.g., shared_ptr); prefer smart pointers to dumb pointers. Otherwise you can leak resources because the order of evaluation of a function's parameters is undefined. (See Item 31.) For example, consider a function taking as its parameters two smart

pointers to new-allocated Widget objects:

void Fun( shared_ptr<Widget> sp1, shared_ptr<Widget> sp2 );

// ...

Fun( shared_ptr<Widget>(new Widget), shared_ptr<Widget>(new Widget) );

Such code is unsafe. The C++ standard gives compilers great leeway to reorder the two expressions building the function's two arguments. In particular, the compiler can interleave execution of the two expressions: Memory allocation (by calling operator new) could be done first for both objects, followed by attempts to call the two Widget constructors. That very nicely sets things up for a leak because if one of the constructor calls throws an exception then the other object's memory will never be released! (See [Sutter02] for details.)

This very subtle problem nonetheless has a very simple solution: Follow the advice to never allocate more than one resource in a single statement, and perform every explicit resource allocation (e.g., new) in its own code statement which immediately gives the resource to an owning object (e.g., shared_ptr). For example:

shared_ptr sp1(new Widget), sp2(new Widget);

Fun( sp1, sp2 );

See also Item 31 for other advantages to using this style.

References

[Alexandrescu00c] ; [Cline99] 31.03-05 ; [Dewhurst03] 24, 67 ; [Meyers96] 9-10 ; [Stroustrup00] 14.3‑4, 25.7, E.3, E.6 ; [Sutter00] 16 ; [Sutter02] 20-21 ; [Vandevoorde03] 20.1.4

Blend static and dynamic polymorphism
judiciously.

Summary

Static and dynamic polymorphism are complementary. Understand their tradeoffs, use each for what it's best at, and mix them to get the best of both worlds.

Discussion

Dynamic polymorphism comes in the form of classes with virtual functions and instances manipulated indirectly (through pointers or references). Static polymorphism involves template classes and template functions.

Polymorphism means two things:

     A given value can have more than one type.

     A given function can accept arguments of types other than the exact types of its formal parameters.

The strength of polymorphism is that the same piece of code can operate on different types, even types that were not known at the time the code was written. Such "post-hoc applicability is the cornerstone of polymorphism because it amplifies the usefulness and reusability of code (see Item 38). (Contrast that with monomorphic code that rigidly operates only on the concrete types it was meant to work with.)

Dynamic polymorphism via public inheritance lets value have more than one type. For example, a Derived* p can be viewed as a pointer to not only a Derived, but to an object of any type Base that's a direct or indirect base of Derived (the subsumption property). Dynamic polymorphism is also referred to as inclusion polymorphism because the set modeled by Base includes the specializations modeled by Derived.

Due to its characteristics, dynamic polymorphism in C++ is best at:

     Uniform manipulation based on superset/subset relationships: Different classes that hold a superset/subset (base/derived) relationship can be treated uniformly. A function that works on Employee objects works also on Secretary objects.

     Static type checking: All types are checked statically in C++.

     Dynamic binding and separate compilation: Code that uses classes in a hierarchy can be compiled apart from the code of the entire hierarchy. This is possible because of the indirection that pointers provide (both to objects and to functions).

     Binary interfacing: Modules can be linked either statically or dynamically, as long as the linked modules lay out the virtual tables the same way.

Static polymorphism via templates also lets a value have more than one type. Inside a template<class T> void f( T t ) { /*...*/ }, t can have any type that can be substituted inside f to render compilable code. This is called an "implicit interface, in contrast to a base class's explicit interface. It achieves the same goal of polymorphism—writing code that operates on multiple types—but in a very different way.

Static polymorphism is best at:

     Uniform manipulation based on syntactic and semantic interface: Types that obey a syntactic and semantic interface can be treated uniformly. Interfaces are syntactic and implicit (not signature-based and explicit), and so allow any type substitution that fits a given syntax. For example, given the statement int i = p->f( 5 ): If p is a pointer to a Base class type, this calls a specific interface function, such as perhaps a virtual int f(int). But if p is of a generic type, this call can bind to a myriad of things, including that it might invoke an overloaded operator-> that returns a type defining the function X f(double) where X is convertible to int.

     Static type checking: All types are checked statically.

     Static binding (prevents separate compilation): All types are bound statically.

     Efficiency: Compile-time evaluation and static binding allow optimizations and efficiencies not available with dynamic binding.

Decide on your priorities, and use each type of polymorphism for its strengths.

Prefer to blend both kinds of polymorphism to combine their benefits while trying not to combine their drawbacks:

     Static helps dynamic: Use static polymorphism to implement dynamically polymorphic interfaces. For example, you might have an abstract base class Command and define various implementations as template</*...*/> class ConcreteCommand : public Command. Examples include implementing the Command and Visitor design patterns (see [Alexandrescu01] and [Sutter04]).

     Dynamic helps static: Offer a generic, comfortable, statically-bound interface, but dispatch dynamically internally so you offer a uniform object layout. Good examples are discriminated union implementations (see [Alexandrescu02] and [Boost]) and tr1::shared_ptr's Deleter parameter (see [C++TR104]).

     Any other blend: Just remember that a bad blend

that combines the weaknesses of both is worse than using only one in isolation, while a good blend that combines the benefits of both is better than either alone. For example, don't put virtual functions into a templated type unless you intend all virtual functions to be instantiated with any use of the type (this is in sharp contrast to non-virtual functions of templated types). The code size hit can be astronomical, and you may overconstrain your generic type by instantiating functionality that is never needed. We made this mistake in the standard facets. Don't make it again.

References

[Alexandrescu01] 10 ; [Alexandrescu02] ; [C++TR104] ; [Gamma95] ; [Stroustrup00] 24.4.1 ; [Sutter00] 3 ; [Sutter02] 1 ; [Sutter04] 17, 35 ; [Vandevoorde03] 14

Partial Bibliography (covering the excerpted Items)

C++ Coding Standards
Herb Sutter and Andrei Alexandrescu
Addison-Wesley Professional, 2005
224 pp., $34.99
ISBN 0321113586

Book Review

The New Standard Model

by Gregory V. Wilson

In physics, the Standard Model is today's baseline explanation of How It All Works. It encompasses quarks, leptons, force-carrying particles—pretty much everything except gravity. From subatomic physics to cosmology, practically everyone builds their theory in its image.

For programmers of my generation, the Standard Model of programming consisted of C, Emacs, Make, UNIX command-line tools such as cat and grep, CVS, and character streams. Now, 25 years later, a replacement is taking shape. Its main elements are Java, the Eclipse IDE, Ant (for building), JUnit (for testing), Subversion (for version control), reflection (for extensibility), and XML (as a universal data-storage format).

So much of this New Standard Model is open source that most of the books describing it—including Java Open Source Programming by Joe Walnes and company—have the phrase in their titles. The first half of JOSP shows you how to build yet another online pet store. Instead of starting with servlets, however, the authors begin by explaining how they will test the application with JUnit and dynamically generated mock objects, and how they will use Hibernate to handle database persistence.

The application itself is then built using WebWork (a Model-View-Controller framework) and SiteMesh (for layout). Search is added using Lucene, XDoclet is used to generate configuration files from metadata embedded in the Java source, and then the authors pause to describe how they communicate via CVS, wikis, mailing lists, IRC, and so on.

And we're not even at page 200 yet.

The second half of the book goes back over the application, replacing the simple throwaway prototypes of the first half with versions that could carry their weight in the real world. Want to know how experienced developers figure out how to manage object lifecycles and dependencies? That's Chapter 14. Look and feel? Chapter 17. There's even some discussion of security, although this material felt like an afterthought and didn't quite live up to the standard set by the rest of the book, which is quite high. The writing is clean, the examples are explained well, and the authors didn't waste time grinding methodological axes. It's definitely not for beginners, but every professional developer will find something useful in this clear, topical survey.

Coder to Developer

When I was a young lad, there weren't many books that would teach you how to program. Oh, there were plenty that talked about this language or that algorithm, but if you wanted to learn the mechanics of developing software that worked, there was Brian Kernighan's Software Tools in Pascal, and very little else.

Twenty-two years later, there's still only a handful to choose from. The good news about Mike Gunderloy's Coder to Developer is that it increases the number by one. This practical, readable book is subtitled, "Tools and Strategies for Delivering Your Software," and that's exactly what it's about. Project planning, source-code control, unit testing, logging, and build management are all there. Importantly, so are newer topics, like building plug-ins for your IDE, code generation, and things you can do to protect your intellectual property.

Coder to Developer is a little more nuts and bolts than Andy Hunt and Dave Thomas's Pragmatic Programmer, but just as well written and just as useful. Two thumbs up.

Effective Software Test Automation

One of the most important features of the "New Standard Model" of programming is its emphasis on unit testing. Just five years after the first version of JUnit was written, an ever-increasing number of programmers actually create and run tests as a matter of course.

But writing tests by hand is still tedious and still requires a fair degree of programming skill. Enter Kanglin Li and Mengqi Wu's Effective Software Test Automation. Over the course of 12 detailed (and sometimes rather intense) chapters, the authors explain how to build a higher level testing tool for .NET programs using reflection (to find and call the methods being tested), CodeDOM (to generate testing code from specifications), and Excel (as a user interface).

Using an application like Excel as a UI may sound strange to UNIX programmers, but thanks to its COM interface, programs can drive it and read data from it with ease. Once QA staff have created a spreadsheet full of tests, the tool described in this book reads in their test cases, generates code to implement those tests, loads the classes to be tested, and runs that code.

The testing tool by itself is interesting and useful, but what I really enjoyed about this book was the authors' explanation of how to build it. Flat text files and handwritten code will always be with us, but structured data and machine-generated code are becoming more important with every passing day. If you'd like a glimpse at how the next generation is going to program, this book is a good place to start.

Greg is a DDJ contributing editor and can be contacted at [email protected] .

Java Open Source Programming
Joe Walnes, Ara Abrahamian, Mike Cannon-Brookes, and Pat Lightbody
Wiley, 2004
459 pp., $45.00
ISBN 0471463620

Coder to Developer: Tools and Strategies for Delivering Your Software
Mike Gunderloy
Sybex, 2004
297 pp., $29.99
ISBN 078214327X

Effective Software Test Automation: Developing an Automated Software Testing Tool
Kanglin Li and Mengqi Wu
Sybex, 2004
408 pp., $44.99
ISBN 0782143202

Recent Releases

Steal This File Sharing Book: What They Won't Tell You About File Sharing
Wallace Wang
No Starch Press, 2004
296 pp., $19.95
ISBN 159327050X

This book is dedicated to the controversial world of online file sharing. Among the book's highlights are chapters on methods of using IRC and newsgroups to share files; "miscellaneous thievery," such as illicit trading of embroidery patterns; how corporations are fighting back with lawsuits, "educational campaigns," and bogus files designed to poison a file sharing network.

Hibernate in Action
Christian Bauer and Gavin King
Manning, 2004
432 pages, $44.95
Ebook, PDF, $22.50
ISBN 193239415X

Hibernate automates a tedious task, the persistence of Java objects with relational database systems, traditionally one of the major problems in application development. This book is the first and only full tutorial, reference, and authoritative guide, and one of the most anticipated books of the year for Hibernate users.

Outsource: Competing in the Global Productivity Race
Ed Yourdon
Prentice Hall Professional Technical Reference, 2004
270 pp., $27.99
ISBN 0131475711

Yourdon explores the impact of offshore outsourcing on the United States. Look for Michael Swaine's review of the book in an upcoming DDJ Programmer's Bookshelf newsletter.

Succeeding with Open Source
Bernard Golden
Addison Wesley Professional, 2004
272 pp., $39.99
ISBN 0321268539

This book presents strategies for selecting open-source software based on a product's characteristics such as quality, support, and longevity.

Contact Us

To contact Dr. Dobb's Programmer's Bookshelf Newsletter, send e-mail to Deirdre Blake, DDJ Managing Editor, at [email protected].

All content copyright 2004, CMP Media LLC.