What I dislike about “The Cucumber Book, Second Edition”: Style issues

I know how much work goes into creating a book. Perfection is not possible with such a detailed piece of work. I was surprised at the number of flaws, though, despite the fact that this book came from a publishing house with a named producer on the copyright page.

There were errors that a decent editing job would have caught, for example an incorrect possessive on page 218 “Here is our recipe, adapted from Michael Feathers’s, …” or the use of “less” on page 222 where “fewer” is the obvious better choice.

Then, there is the author’s use of the word “check” in place of “test” in some places but without apparent consistency in usage or even a clear view of a difference between the two terms with respect to software quality management. There is no glossary to enlighten the reader here as to what they mean with their choices of “check” or “test,” which is inconsistent with the apparent motive of the book as an educational tool. It might be that the authors don’t know or care about any difference between the two words, which is more consistent with a sales role than one promoting technical excellence.

The “sales” strategy shows up in many places in the book, for example, on Page 98: “We’re not trying to suggest that you give up on BDD and go back to cowboy coding, …” The clear implication is that these are the only two choices, which is nonsense and may be insulting to those of who know better, but a useful way to promote BDD and Cucumber to people who don’t know that there are other options.

It pops up earlier on page XV with the personification of Cucumber: “Cucumber is a friendly tool. It wants to be part of your team, … Business stakeholders warm to Cucumber’s open attitude…” Personally I find this weird and creepy.

On page 6 there is a section called “Living Documentation” about how, in contrast to traditional specifications (e.g., as one would see in a waterfall-like SDLC), with the Gherkin-language Cucumber specs “…you can give them to a computer at any time to tell you how accurate they are.” There’s that personification again, but there is a serious weakness here because behind the Gherkin steps there is a potentially many lines of glue code that do the real work, and as the authors admit on page 33, one would have to “… read the code to work out what it does.” The “living documentation” is no more “living” than the keywords of Robot Framework; the details are hidden to anybody who doesn’t want to read glue code or, to verify runtime behavior, step through it with a debugger. These details also can change in ways invisible to anybody who doesn’t want to study the logs of whatever system is used as code repository. Sometimes engineers have good reason to make changes here, even though they are hidden to other roles; I’ve done these things myself.

I don’t buy the “living documentation” claim for the Gherkin language with Cucumber; although it is better than completely separate docs, it needs to get much better still before the behavior of automation driving and measuring the SUT really is transparent or automation can help people manage the quality knowledge that the automation produces. (Disclosure: those things are what MetaAutomation is all about.)

IMO Cucumber and Gherkin go in the right direction, but only about 10% of the distance needed, towards sharing quality knowledge around the team in a way that is both detailed and trustworthy.

There are some significant errors that could confuse the reader or cause him/her to make mistakes. For example, the figure on page 38 is not consistent with the code example on page 27 (where did the scenarios layer go?).

On page 39, there is a suggestion to skip ahead to page 50 if the reader is already fluent in regular expressions, but pages 41-42 describe an important Cucumber flaw that the reader needs to be aware of no matter how well (s)he knows regular expressions. On page 42: “You obviously need to be careful in this situation.” I doubt the authors intended to set a tiger trap there, but that is what the oversight amounts to.

Previous posts in this series:

Future posts (with links, as the posts happen):

No Comments

Add a Comment

Sign up here for emails with bites of wisdom on quality automation and MetaAutomation

Recent Blog Posts