Tuesday, January 29, 2013

Effective C++11: Content and Status

Before I summarize the Items I currently plan to include in Effective C++11 ("EC++11"), I'd like to explain a little about how I come up with the guidelines in my books.

It'd be sweet to imagine that I develop all the guidelines myself. If you're very technical about it, I do. I come up with all my own Item wordings, and I write all my own Item justifications. But the ideas behind the guidelines have generally already fought their way to acceptance in the C++ community. It's this acceptance that gives me confidence that the advice in the guidelines is both accurate and useful. My Effective books strive to summarize practices that are known to be effective, not to introduce new practices I hope will be.

In the case of C++11, the Standard is only about 18 months old, and some parts of it are yet to be implemented by major compilers. The experience with C++11 that is necessary to identify useful advice is therefore limited. But even the features that have not seen widespread use have been discussed and debated for years, and sometimes that gives rise to "observations" about those features that seem likely to be important. Consider, for example, what happens in a destructor for a std::future. If the future came from std::async, the future's destructor blocks until the asynchronously running thread completes. If the future did not come from std::async, the future's destructor doesn't block. That's already interesting, but, in my mind, it becomes even more interesting when combined with the observation that the destructor for a "joinable" std::thread calls the terminate function.  So we have three different behaviors for a single high-level concept: destruction of the object "responsible" for another thread.

I think this divergent behavior is likely to trip people up, and that gets it on my candidate list for EC++11. But what is the Item?  What is the advice? I could go with the lame-o "Understand destructor behavior in std::future and std::thread," but that's just cloaking an excuse to describe language rules in guideline form. I'm not above doing that when I can't think of anything better, but I prefer to find a way to offer advice that could be checked by a tool or in a code review. "Understand" rules fail that test.

(As an aside, the behavior of the destructors for std::futures produced by std::async is controversial and may change in the next revision of C++ (currently forecast to be in 2014). Some implementations already deviate from the behavior dictated by the Standard. That muddies the water yet further, but that's a problem for me and my book, not this blog post.)

You can think of "observations" about C++11 as proto-Items. They're not yet in guideline form, but they seem important enough to justify trying to find a way to work them into the book. Whether they'll make the book, and, if so, whether they'll do it as a standalone Item or as a side-discussion in another Item, I don't yet know.

At last year's C++ and Beyond, I gave a talk entitled "Initial Thoughts on Effective C++11." It had my usual guideline format. I also gave a talk on "Secrets of the C++11 Threading API," which consisted of observations about C++11's threading support.The material in those talks, combined with the feedback I got from giving them and mixed in with my experience explaining the idea of universal references, ultimately yielded the initial list of candiate Items for EC++11. The current snapshot of my vision for Effective C++11 is:

Moving from C++98 to C++11

  • Prefer auto to explicit type declarations.
  • Remember that auto + { expr }std::initializer_list.
  • Prefer nullptr to 0 and NULL.
  • Prefer enum classes to enums.
  • Prefer alias templates to typedefs.
  • Declare overriding functions override.
  • Distinguish () and {} when creating objects.
  • Prefer emplacement to insertion.
  • Declare functions noexcept whenever possible.
  • Make const member functions thread-safe.
  • Avoid std::enable_if in function signatures.
  • Handle iterators where copying means moving.

Rvalue References, Move Semantics, and Perfect Forwarding

  • Distinguish universal references from rvalue references.
  • Avoid overloading on universal references.
  • Pass and return rvalue references via std::move, universal references via std::forward.
  • Assume that move operations are not present, not cheap, and not used.
  • Be aware of perfect forwarding failure cases. 
  • Understand reference collapsing.

Secrets of the C++11 Threading API

  • Thread construction may throw.
  • Destroying a joinable thread calls terminate.
  • Arguments passed to std::thread, std::async, and std::call_once are unconditionally copied.
  • std::async is really two different functions with somewhat different APIs.
  • Futures from std::async are special.
  • void futures can be used for interthread communication.
  • To poll a future, use wait_for with a zero timeout.
  • Native handles let you go beyond the C++11 API.
  • Clock adjustments affect _until functions.

Lambda Expressions

  • Prefer lambdas to std::bind.
  • Prefer lambdas to variadic arguments for threading functions
  • Beware default captures in member functions.

Smart Pointers

  • Use std::make_shared whenever possible.
  • Prefer pass-by-ref-to-const to pass-by-value for std::shared_ptrs.

Miscellaneous

  • Pass by value when you’ll copy your parameter.
  • Keep abreast of standardization developments.
The number of Items on this list, the wording they have, the order in which they will occur, and whether they will ultimately be present are not just subject to change, they will change. This is especially true for the material pertaining to the threading API, because those "Items" are still just observations. But that's what my draft TOC looks like right now.

I also have a set of candidate guidelines that I currently feel are less important and hence less likely to make the book. This list will also change over time, but for your voyeuristic pleasure, this is what it contains:
  • Prefer non-member begin/end to member versions.
  • Declare std::thread and std::future members last.
  • For copyable types, view move as an optimization of copy.
  • Understand decltype.
  • Use std::compare_exchange_weak in loops.
If you have comments regarding any of the potential guidelines above, or if you have suggestions about what's not above but you believe should be, feel free to let me know, either as comments on the blog or via email: smeyers@aristeia.com.

"How much of this book have you written?," you may be wondering. None. Not a word. Zero percent. I haven't started writing, in part because I've allowed myself to get distracted by things like, um, creating blog entries...

But wording is everything. If you change the question to "How much of the work required to write this book have you already done?," the answer changes.  When I announced the existence of my annotated training materials for C++11, I explained that my approach to writing a book consists of three steps:
  1. Master the material.
  2. Figure out what "story" I want to tell, i.e., what to cover, what to omit, what order to cover things in, what examples to use, etc.
  3. Write it up.
I went on to break step 2 down as follows:
  • 2a: Come up with a story that I think will work, i.e., that will effectively convey the technical information.
  • 2b: Develop a training course corresponding to that story.
  • 2c: Deliver the training course to professional developers and see how well the story works. In places where it doesn't work as well as it should, return to step 2a and iterate until everything is satisfactory.
 For EC++11, I've pretty much completed steps 1 and 2, so from that perspective, I'm two-thirds done with the book :-) In theory, I know what I need to say. I just need to write it down. In reality, that understates the difficulty of the work that's still to be done, but to some degree, what remains is an IO-bound operation.

I would hope it goes without saying that you can't have too many iterations of steps 2a-2b-2c. Every time I present the material, I learn things about how I can do a better job. Sometimes it's about something I've said that was confusing or unnecessary. Sometimes it's about something I didn't say, but should have. Sometimes it's about a relationship between what I'm discussing and another topic that seemed completely independent to me, but didn't to the people I was working with. To that end, I'll be making several presentations of a new training course called Effective C++11 Programming several times this year. The first is slated to take place in June. I'll post details soon.

For the next few months, I'm doing my best to keep my calendar free. I need time to write Effective C++11. You know how slow IO-bound operations can be.

Scott

Effective C++11: Background

I've mentioned in some earlier posts that I plan to start writing a new book, Effective C++11.  The purpose of this post is to tell you a little bit about it. Lest there be confusion, let me emphasize that there is no book yet. If everything falls into place the way I hope it will, there will be a book about 10 months from now. If. I'm not making any promises.

If you're looking for information on the content of Effective C+11, this is the wrong place to seek it. I had originally planned to include a content summary, but once I'd written the background information that follows, I realized that the post was already too long. So the content information will go in a separate post.


People have been asking me to write Effective C++11 since before it would have been possible to give it that title. I started getting requests when the new version of the language, then known as C++0x, was still under development. I had a ready reply for such requests, aside from my considerable reluctance to write a book about a language that was still in flux. (Poor Anthony Williams' C++ Concurrency in Action remained in publishing purgatory for nearly three years, because he had the misfortune to publish an "early access" digital draft two years before the C++ Standard it corresponded to settled down. As a result, he had to keep revising the draft as updates to the emerging Standard were made, and that cannot have been fun. The result was worth both his effort and our patience, because the book is excellent. I strongly encourage you to consider buying it. I have. But I'm really glad I didn't have to go through the ordeal of writing it.)

My ready reply to requests to whip out Effective C++Whatever was that it's not possible to describe how to use a technology effectively until the community has enough experience with the technology to know what truly works and what doesn't. We'd all like to skip over experiencing the disappointment of what seem like great ideas that fail to pan out. We'd like to instantly come up with the nifty applications of features in ways nobody had foreseen. That'd be great. But as far as I know, the only way to separate the effective uses of C++11 from the ineffective ones is to try as many things as we can, then see what ends up in which pile. That takes time.

In truth, most people didn't ask for Effective C++Whatever. They asked for a new edition of Effective C++. It was the obvious thing to ask for, and it was the obvious thing for me to write, but it presented me with a problem I didn't know how to overcome.

The problem was (and is) that I constrain myself to books with no more than 300 pages. There is some wiggle room in that constraint, because I don't count front matter (preface and tables of contents, etc.--generally stuff numbered using Roman numerals), and if I had to, I'd probably be willing to ignore pages comprising the index. Nevertheless, my goal is to avoid producing a book with a page number higher than 300. The current edition of Effective C++ (available at fine bookstores everywhere, not to mention at a variety of illegal download sites, sigh) has, if you ignore the appendices and the index, a maximum page number of 272. That doesn't leave a lot of room for new material. And, as I've blogged about elsewhere, the material that's currently in the book remains largely valid under C++11. I didn't want to jettison a lot of useful material that's as valid under C++11 as under C++98, but I'm serious about the advantages of comparatively short books, so I didn't want to exceed the 300-page barrier, either.

The page limit problem held me back at least as much as the lack-of-experience problem. I knew that time would address the experience issue, but 300 pages wasn't going to get any bigger, no matter how long I waited. (Yes, I think like a programmer, so I couldn't help but toy with the ideas of playing games with smaller font sizes, narrower margins, page numbering using bases other than 10, and eliminating page numbers entirely. But cheating's less fun when the rules you're evading are the ones you made up in the first place.)

Last year, I experienced the proverbial brainsquall, and I realized that if most of Effective C++ remains valid under C++11, the solution is to not write a new edition of that book, but to write a new book. A book devoted to making effective use of the features unique to C++11. A book to complement Effective C++. That's my plan for Effective C++11:  to write a book describing how to make effective use of the features and capabilities in C++11 that are not present in C++98. A book with content entirely separate from my other C++ books and also largely separate from the content of my C++11 Overview Materials. In other words, all new stuff.  New from me, anyway.

The page constraint was thus vanquished, and experience with C++11 was slowly piling up on the information superhighway, but I had another concern. When I wrote my other books, I knew how they'd be published: as one or two colors of ink on more or less white paper of a fixed size. But the future of publishing was clearly digital, and I didn't know what it meant to produce a manuscript that should ultimately look good and be useful as both ink on paper and pixels on a screen, especially when some screens were monochrome (e.g., Kindle), and screen sizes varied from those of smart phones to those of UHDTV-capable monitors. During 2008-2010, I spent some time agonizing over this issue in my blog for Fastware!, a book that never came to be. I even gave a talk at a publishing conference about my concerns.

To be honest, I'm still not sure how to approach writing a manuscript when the result is to be published on multiple platforms, but analysis paralysis loses its appeal after a while, so I finally decided that if I don't know what the right way is, I might as well take a guess and see what happens. Exactly what that will mean in practice, I'm not sure, but my current plan is to write using Microsoft Word using lots of styles, and my assumption is that whatever manuscript format looks to be "right" when I have a manuscript ready to go, somebody will be able to figure out how to translate what I have in Word into that format.

Okay, having slogged through my whining about lack of experience, page limits, and manuscript preparation, you'd like to think I'll finally do something with a payoff for you. Something like offer some details about what will be in the book.  That I will. In my next post, which I plan to start writing immediately after publishing this one. Stay tuned.

Scott

Wednesday, January 23, 2013

Effective Effective Books

For the cover of the first edition of
Effective C++, I envisioned Alexander
the Great cutting the Gordian Knot.
I'm getting ready to start work on Effective C++11 (about which I'll have more to say in a later blog post), and this week I've been reviewing a manuscript for a new book in my Effective Software Development Series, so recently I've been thinking a lot about what makes an effective Effective book.

Effective books consist of a collection of technical essays ("Items"), where each essay's title comprises advice you should follow, and each essay's body consists of a rationale for the advice. In the third edition of Effective C++, for example, Item 37 is "Never redefine a function's inherited default parameter value."

This format has always seemed pretty straightforward to me, but having reviewed dozens of proposals and manuscripts for my series, it's clear that it's not straightforward to everybody. A few years ago, I wrote up the following guidelines for authors of prospective Effective books. Partly to remind myself of my own advice as I embark on a new book, and partly to have a place to point people who express interest in writing a book for my series, I thought I'd publish my guidance here.

Item 1: Keep Items short.

One of the things readers like best about Effective C++ is the brevity of the Items.  They're generally only 4-5 pages long, and that means that one can be read while waiting for a meeting to begin, during a quick break, even while using the bathroom.  I discovered this when I came out with my second book (More Effective C++), in which some items run for 10-20 pages.  Big mistake!  People want bite-sized chunks of useful information from an Effective book.  Give it to them.

Frankly, the constraint that Items be short is good for you as an author, because it forces you to think hard about what really needs to be included and what can be omitted (see below).  Also, it allows you to produce a book of typically under 300 pages, and a book of that length is something you've got half a chance of keeping in your head all at once.

Regarding overall book length, there are two ways to approach the matter.  It's a lot like packing for a trip.  You can either:
  • Choose all the stuff that you think you need, then find a big enough suitcase to hold it all, or
  • Choose the suitcase first, prioritize everything, then put in as many high-priority items as will fit.  
Effective books generally follow the latter strategy.

Think about your goals for your book.  Is it to tell your readers everything they need to know, or is it to tell them the most important things?  Remember that the longer your book, the less likely your readers will read all of it.  So what would you rather have?  A 250 page book that almost all readers read almost all of or a 500 page book that most readers read about half of?

It's your book, of course, and it's most important that you be happy with it, but you might bear in mind that I've published 140 Items on C++ programming spread across about 800 pages, but I did it in 3 different books.  I think my readers like it better that way, because there's less for them to digest at one time.  I know I like it better the way I did it, because I find it a lot easier to keep no more than 300 pages of material straight than to try to wrestle with 800 pages at once.  Also, I like knowing that my readers are likely to read each book all the way through.  I hate it when I work hard at writing something, only to find that some people stopped reading before they got to the end.  I have a story I want to tell them, and it's important to me that they get the entire story.

If you have a lot to say, there's no law that says you have to say it in a single book. Splitting it across multiple books may end up serving everybody better.

Bear in mind that Effective books are designed to be "the standard second book" on their topic.  You should assume that readers know the basics and have another comprehensive reference available to them.

Item 2: Put Item titles in the imperative.

People read Effective books for advice, to learn "the things the experts almost always do--or almost always avoid doing."  They want to be told what to do or what not to do, so each item should give them an order: Do this or don't do that (ideally the former--see below).  Statements are not as helpful as imperatives, so don't use statements as Item titles.

As an example, I could have worded this Item as "Imperative Item titles are good," but that's not advice, it's just a statement.  "Put Item titles in the imperative" is advice.  Your readers want advice.  Provide it.

Alas, they sometimes want advice when what they really need is information.  Fortunately, there's a way to give them both: use imperatives that begin with "Understand" or "Familiarize yourself with" or "Be aware of" or things of that ilk.  For example, if you think that people generally fail to grasp the subtleties of some topic XYZ and you feel that they really need to understand it in order to be effective software developers, consider a title like, "Familiarize yourself with the subtlties of XYZ."  It's still an imperative.

After reading your book, people will want a convenient summary of the advice it contains.  If each Item title is an imperative, the book's TOC (Table of Contents) will be a summary of its advice, and that should be one of your goals: to have the TOC summarize the advice in the book.

Item 3: Make Item advice as specific as possible.

The best advice is so specific, it can be checked by a machine.  In fact, many of the guidelines I put in Effective C++ have been incorporated into static analysis tools.  Specific advice is also good for code reviews, because it eliminates the interpretation factor; readers don't argue over what a particular Item means.  They might argue over whether a particular Item is justified (see below), but if the advice is specific, they won't argue over what it means.

If you are having trouble making a guideline specific, it could be because the topic you are writing about in that Item is too general.  If that's the case, perhaps you need to break it down into two or more separate (and more specific) guidelines.  For example, if you're trying to offer advice about the proper use of inheritance, but you find that it's hard to be specific, because interface and implementation inheritance are so different, consider writing two items, one about interface inheritance, the other about implementation inheritance.

Item 4: Word Item titles carefully.

Your TOC summarizes your book's advice.  Furthermore, your TOC consists primarily of your Item titles.  That means that the most important sentences in your book are the ones making up your Item titles.  All words in a book are worth agonizing over, but some are more agonizable than others, and the ones in your Item titles are the most agonizable of all.  They make up the advice you want your readers to remember, even if they forget everything else in the book.  As a result, you want your Item titles to (1) be easy to remember and (2) accurately summarize your advice on the topic addressed by the Item.

Resist the urge to choose titles that are catchy, but not informative.  One manuscript I read had an item on using profilers to guide optimization efforts, and the Item title was "Optimize optimally."  This is catchy, but it doesn't summarize the advice in the Item.  Item titles are different from article titles.  Authors often choose enigmatic article titles to intrigue people into reading the article.  That's not the goal in an Effective Item.  Readers already have the book. You can expect them to read it.  The goal of an Item title is to summarize in a few words the advice that will take several pages to justify.  Remember: the Item title is "what."  The Item body is "why."

When I write my books, I typically revise the wording of Items several times.  I'll start with what I think I want to say, but after I've written an Item's body, I'll realize that my justification doesn't really back the title, so I'll revise the title.  Or after I've written other Items, I'll discover that some of what what I wanted to say in Item n is now in Item m, so I'll go back and revise Item n's title to reflect the fact that it no longer addresses the concerns of Item m.

Any time my Item title is too long to fit on a single line, I'll try to come up with a shorter way to say it.  Short Item titles are easier to remember than longer ones, and my goal is for my readers to remember all the titles of all the Items.  The easier I make it for them to do that, the better my odds of achieving my goal.

You'll note that several of the other Items in this document relate to Item wordings.  That's no accident.  It's a reflection of the importance of Item titles to Effective books.  You've got just a few words to summarize the lessons of several pages of often complex material.  Choose them carefully.  They're the most important words in your book.

Item 5: Prefer guidelines that say what to do over what not to do.

Guidelines that tell people what they should do are more useful than guidelines that tell them what they should not do.  If a programmer wants to accomplish task X, knowing that they should not do A, B, or C may narrow the design space, but it doesn't really tell them how to accomplish X.  Any time you are tempted to start an item with "Avoid" or "Never", imagine the following conversation with your readers:
       You:         Avoid doing A.
       Readers:   But if I don't do A, how can I accomplish X?
       You:         Do B instead.

If you can come up with such a conversation, you probably want to word your Item as something like "Prefer B to A for X."  (See below for more information on words like "avoid" and "prefer" in Item titles.)

Item 6: Tell the truth and nothing but the truth, but not necessarily the whole truth.

Effective books are short by design, typically only about 5 pages per Item.  With such limited space, it's important to include only information readers really need to know.  Your goal should be to help your readers, not to demonstrate your mastery of history or trivia, etc.  After all, one of the things they are paying you for is deciding what they don't need to know.

At the same time, you lose your credibility if you lie to your readers, so you must never lie.  To avoid lying while also shielding them from information they don't need to know, you will need to fall back on weasel words: typically, generally, usually, etc.  You don't want to use these more than you have to, because readers will notice them, but if your choices are a two-page digression on how some bizarre machine or compiler that almost nobody uses does something in a strange way or slipping "virtually" in front of "all implementations," then "virtually" and its kin are your friends.

Item 7: Back Items with solid technical arguments.

The most common weakness I see in prospective Effective books is that the Item rationales fail to make convincing cases for the Items' advice.  This is critical!  Remember, you're telling somebody what to do.  You're probably asking them to change the way they do things.  If they're going to change their habits, and especially if they're going to let you push them around, they'll demand a good reason, and it's your job to give it to them.  You should assume that your readership is smart, experienced, and critical.  Effective books aren't introductory, so your readers already know some of what you're talking about.  Some of it they know as well as you do.  If you tell people to do X, but fail to acknowledge that it's impractical some of the time, they'll notice, and you'll lose credibility.  If you tell them that they have to do X because of Y, but Y isn't true, they'll notice, and again, you'll lose credibility.  You can't afford to lose credibility, because if you're not credible, why should
your readers take your advice?

In addition, there are almost certainly going to be exceptions to any advice you can offer, and one of the most important things you must do as an author is explain to your readers when your advice applies and when it does not.  The Item rationale is the place where you do that, at least implicitly.  For example, I spend a lot of time in my C++ books talking about how to prevent resource leaks, and much of my advice boils down to, "Do this, because it helps prevent resource leaks."  At one point, I was talking to engineers who work on the software that runs inside missiles.  Their programs run until the missile hits its target.  They don't care about leaking resources at program shutdown, because their programs never shut down.  They stop running only when the bomb goes boom.  As a result, they feel free to ignore some of my advice, and that's perfectly reasonable.  But the only way they know that that is perfectly reasonable is because my books make clear the technical motivation for the advice I give.  When that motivation fails to apply, so does the advice.

Item 8: End each Item with a summary of its advice.

The old saw is "Tell 'em what you're going to tell 'em; tell 'em; tell 'em what you told 'em."  Effective Items are similar, but not quite the same: Tell them what they need to remember; justify it; remind them of what they need to remember.

If you've worded your Items correctly (see above) what they need to remember is the Item title, a single sentence of only a few words.  The justification typically runs 4-5 pages, and that's where you deal with implementation strategies, portability issues, exceptions to the rules, explanations of why things are the way they are, etc.  By the time you're done with that, there is every likelihood that your readers have forgotten the main point you initially set out to make.  You therefore need to remind them.  It doesn't need to be long-winded; a sentence, short paragraph, or set of bullet points is all you need.  For example, for an Item with this title,
  Write operator delete if you write operator new.
I end this way (9 pages later, sigh):
Now, it's interesting to see how custom memory management routines can improve program performance, and it's worthwhile to see how such routines can be encapsulated inside a class like Pool, but let us not lose sight of the main point. That point is that operator new and operator delete need to work together, so if you write operator new, be sure to write operator delete, as well.
For the third edition of Effective C++, I added a short list of bullet points to the end of each Item called "Things to Remember." That allowed me to eliminate the summary paragraphs from many Items while still allowing me to remind readers of each Item's most important information.

Item 9: Know how to modulate the stridency of Item titles.

Virtually every rule has exceptions, but some rules have more exceptions than others.  The wording of your Item titles should reflect the likelihood that your readers will encounter exceptions.  In real life, for example, we should (almost) always buckle up for safety, (almost) never drink and drive, and (typically) consider taking public transit when it is available.  Those three words--always, never, and consider--are three of the five words I've found useful when wording Item titles.  Here's the full scale of advice urgency, from Always to Never:
  •   Always
  •   Prefer
  •   Consider
  •   Avoid
  •   Never
The default is "Always," so it's generally implicit.  I could have worded one of the guidelines above  this way, for example,
Always put Item titles in the imperative.
but "Always" here adds little, so there's no point in including it. 

Because every rule has exceptions, there's an implicit "Almost" in front of any rule that begins with "Always" or "Never." However, including "Almost" in Item titles draws attention to the existence of the exceptions, and that's not what we want readers to focus on.  For example, consider how wishy-washy this looks:
Almost always put Item titles in the imperative.
Please!  Take a stand!  That's one of the things that readers like about Effective books: the authors give specific advice instead of bland platitudes.  Each Item has a rationale,  so any situation not covered by the rationale can naturally be interpreted as being an exception to the rule.  Hence the implicit nature of "Almost."

Item 10: Cross reference liberally.

Effective books are collections of essays.  Each is specific and constrained (see above), but collectively they cover a lot of territory.  The territories they cover necessarily abut and overlap, and that means that almost no Item stands alone.  When there are relationships among Items, readers need to know that.  That's where Item cross-referencs come in.  If Item A gives a detailed discussion of a topic that's relevant to Item B, B should probably have a cross-reference to A.  (A might also have a cross-reference to B.)  If Item A strengthens the rationale for Item B, B should probably have a reference to A.  If Items A and B cover disjunctive situations, both should probably refer to one another (e.g., "Item A explains why you need to do X to achieve Y, but sometimes your goal isn't Y, it's Z.  When that's the case, the advice in Item A fails to apply...").

In the end, most everything is related to everything else in some way or another.  You don't need to point out all relationships to your readers (see above about omitting information they don't need to know), but you should definitely use cross references to point out the ones that are important in making effective use of whatever technology you are writing about.

Item 11: Minimize use of footnotes.

Footnotes make a book look more formal and academic.  Effective books tend to shoot for a more casual, informal approach.  As a result, it's best to avoid footnotes whenever possible.  In general, you'll find that information you want to footnote can either be eliminated or incorporated into the body of your discussion.

Item 12: Be consistent when referring to yourself and your readers.

This is a grammatical "person" issue: first person, second person, or third person?  When you refer to the author of the book, do you say "I" (first person) or "the author" (third person)?  When you refer to the reader of the book, do you say "you" (second person) or "the reader" (third person)?  The choices are nowhere near as important as that you abide by them consistently.  I like to envision Effective books as one-on-one informal conversations between the author(s) and each reader, so I prefer using first person for the author and second person for the reader, e.g., "Now, when I say that XYZ is a good idea, I suspect you'll wonder if I'm off my rocker."  Third person works, too, though I think it's stuffy: "When considering the author's recommendation to do XYZ, the reader may be forgiven for wondering if the author is off his rocker."

Bottom line: I see too many manuscripts where authors can't decide how to refer to themselves or their readers.  Make the decision early on, write it down so you remember it, and adhere to it consistently.

Item 13: Seek out ruthless pre-publication reviewers.

No matter how careful you are, odds are that the book you write will contain errors or other problems.  That being the case, it's in everybody's interest to find out about them as soon as possible.  Ideally, you'll find out about them before the book is actually published, thus giving you a chance to fix them before your masterpiece is loosed on the world.

There are many ways to get good pre-pub feedback, but all have one thing in common: they are based on finding reviewers who are willing and able to tell you how your book can be improved and who don't pull punches.  What you want to hear is that your manuscript is wonderful and is ready for publication, but what you need to hear is that some words are misspelled, some diagrams are confusing, some topics are technically incorrect, the way you've organized things makes no sense, and that you've failed to consider some aspects of the material that are important.

Providing such feedback is hard work, and that means that you're unlikely to find people willing to give it to you unless you go looking for them.  Seek them out.  Tell them you want to know everything that is wrong with your manuscript.  Make it clear that a better book is more important to you than an unbruised ego.  Ask your friends to be reviewers only if (1) you believe they are willing to be brutal in their comments and (2) you honestly believe that your friendship can withstand the pressure.  But don't rely only on your friends.  Seek out individuals who are representative of your target audience, and ask them to tell you what they think.  (Your friends are unlikely to be good at this.  For one thing, there's a very good chance that your friends know more about what you're writing about than your average target readers does.  After all, your friends hang out with you.  Your readers don't.)

When I circulated an early draft of my second book, I got back comments from one reviewer who, having savaged the first 30-40 pages, concluded with "It doesn't get any better after that."  It took me a couple of days to recover from that, but once I did, I was able to dispassionately evaluate the comments and conclude that they were accurate.  Then I rewrote the book, making extensive revisions.  The resulting book was much better than it would have been had I received only comments telling me that this or that detail needed tweaking.

It's nice to hear nice things about what you've written.  You're much more likely to hear them after your book comes out if you've heard awful things when the book is in progress.  Seek out people who will tell you those awful things in advance so you won't have to hear them later.

Tuesday, January 15, 2013

New ESDS Book: Effective JavaScript

I'm very pleased to announce that the ninth book in my Effective Software Development Series has recently been published, David Herman's Effective JavaScript. In my comments to David on a pre-publication manuscript, I wrote:
These chapters are a very pleasant read.  The text flows well, and the explanations are such that I generally had no trouble understanding them, even though I don't know JavaScript.   I think this will be a very nice book.
Others who do know JavaScript seem to agree that it's turned out that way.  Reginald Braithwaite recently posted a quite positive review, and the review at Utah JS starts out this way: "Effective JavaScript by David Herman is the best JavaScript book I’ve ever read." Currently, there are six reviews at Amazon, and all award perfect fives.

If you're a JavaScript programmer, I encourage you to check out Effective JavaScript.

Scott



Monday, January 7, 2013

Recent Developments regarding C&B

2013 is only a week old, and already there's been a lot of action on the C++ and Beyond front. That's especially the case if you're willing to fully embrace zero-based indexing (thus viewing December 31, 2012, as January 0, 2013), because that means that the following announcements have come out this year:
That makes six sessions from C&B 2012 we and Channel 9 have so far made available. Two additional sessions are slated to be published at Channel 9 soon.

As always, the best way to be kept up to date on developments regarding C++ and Beyond is to do one or more of the following:
I look forward to another great C++ and Beyond near the end of this year, and I hope you'll be part of it. We'll announce more details when they are available.

Scott