PragPub 2012-04: Issue #34

Table of Contents

Features

Technical Blogging

by Michael Swaine

We talk with the author of Technical Blogging about why and how technical people shpould blog.

Sand Piles and Software

by Zach Dennis

Building software one grain of sand at a time—and managing the landslides when the sand piles get too steep.

Scala for the Intrigued

by Venkat Subramaniam

In the eighth installment in his series on the Scala language, Venkat show how Scala almost makes XML pleasant to deal with.

The Pragmatic Defense

by Jim Bonang

Jim shows how to write methods with built-in defenses that allow you to quickly find the fault underlying a failure.

Departments

Up Front

by Michael Swaine

Mike interrupts his summary of the contents of this issue to invite you to write an article for us.

Choice Bits

Drinking from the Twitter firehose.

Meet the Team

Meet Kay Keppler, development editor and science fiction author.

Calendar

Author sightings, upcoming conferences, and other events of note.

Shady Illuminations

by John Shade

Asked to reveal his philosophy of life, John says “No.”

But Wait, There’s More...

Coming attractions and where to go from here.

Except where otherwise indicated, entire contents copyright © 2012 The Pragmatic Programmers.

Feel free to distribute this magazine (in whole, and for free) to anyone you want. However, you may not sell this magazine or its content, nor extract and use more than a paragraph of content in some other publication without our permission.

Published monthly in PDF, mobi, and epub formats by The Pragmatic Programmers, LLC, Dallas, TX, and Raleigh, NC. E-Mail support@pragprog.com, phone +1-800-699-7764. The editor is Michael Swaine (mailto:michael@pragprog.com). Visit us at http://pragprog.com

ISSN: 1948-3562

Up Front

Write for Us

by Michael Swaine

This is the thirty-fourth monthly issue of PragPub, the DRM-free, ad-free, and just-plain-free magazine from The Pragmatic Programmers. We publish simultaneously in every format we can think of, so I don’t know you’re reading these words in html on our website, in pdf, in epub on an iPxd or some other epub-friendly mobile device, or in mobi on your Kindle.

But however you’re reading it, have you ever wondered where the articles come from?

I’m glad you let me suggest that you think about asking that question.

They could come from you.

I’m always looking for good articles on subjects of interest to software developers. If you have one in you, let me know. To get a feel for the appropriate style and length and the subjects that interest us, you just need to read some articles.

For example....

Antonio Cangiano leads off this issue in an interview about technical blogging. We just published Antonio’s book of that name, and nobody knows more about the subject than he does.

Also in this issue, Zach Dennis looks at building software as piling up grains of sand one at a time—and then managing the landslides when the sand piles get too steep. And Jim Bonang introduces The Pragmatic Defense, a comprehensive strategy in which you write methods with built-in defenses that allow you to quickly find the fault underlying a failure.

Venkat Subramaniam is back with another article on the Scala language. This month Venkat shows how Scala handles well-formed XML syntax as regular language syntax. In fact, Scala goes much farther than that in its support of XML as a first class language citizen, as you’ll learn in this enlightening article.

And there’s John Shade’s monthly column and all the usual departments. I hope you enjoy it. And maybe it will inspire you to write an article of your own.

Choice Bits

Mondriaan invents the Scrum/Kanban board.

Plumbing the depths of the twitterstream and keeping our feet dry.

What’s Hot

Top-Ten lists are passé—ours goes to 11. These are the top titles that folks are interested in currently, along with their rank from last month. This is based solely on direct sales from our online store.

1^ | NEW | The Rails View
2^ | NEW | tmux
3v | 1 | Agile Web Development with Rails
4^ | NEW | Build Awesome Command-Line Applications in Ruby
5v | 3 | The Cucumber Book
6^ | NEW | The dRuby Book
7^ | NEW | Deploying with JRuby
8v | 4 | Programming Ruby 1.9
9v | 7 | Seven Databases in Seven Weeks
10v | 5 | Deploying Rails
11v | 6 | The RSpec Book

This Coding Life

New Hobby: using Apple tag lines as commit messages: “This Changes Everything. Again.” — @‪jroper‬

Saying Java is awesome because it has awesome IDE support is like saying being in ICU is awesome because it has awesome life support. — @‪jroper‬

APL is the most expressive programming language I’ve ever seen. #spse2012 — @‪staffannoteberg‬

Did you know that there was a RFC (3092) that describes the etymology of Foo, Bar, Baz? http://bit.ly/zFnApZ (Yeah, I didn’t either...) — @‪scottdavis99‬

@searls I like “small is having nowhere to hide.” Also definition of faster. Dubious about “growing a team will come naturally.” Good preso. — @‪marick‬

It seems Mondriaan already invented the Scrum/Kanban board in 1917: http://ow.ly/i/vgXY — @‪jurgenappelo‬

Amazing how many teams “can’t do pair programming” just because of their furniture. — @‪tottinge‬

“We want an open and welcome community. Also, our next hackathon will be held at The Lusty Leopard.”—brogrammer — @‪bphogan‬

IRL

Those who *do* remember the past are condemned to be inadvertently patronising to those who’re too young to. — @‪alancfrancis‬

Did you know that the word “hipster” was first used in the 1940s? That’s right. They had that word before it was cool. — @‪bphogan‬

Is it “feed a cold, starve a fever” or the other way around? I ask because we have five boxes of Thin Mints. — @‪marick‬

We ran out of Dalwhinnie half way through your pour, so we topped it off with Macallan. #ScotchInTheSuburbs — @‪scottdavis99‬

Yes, Cinderella lost her volleyball games because her coach was a pumpkin, but also because she ran away from the ball! — @‪petdance‬

All of these supercomputers in our pockets, yet when I fall asleep with the TV on, none of them turn off Carson Daly. — @‪therealadam‬

This Magic Moment

Hey, anyone remember last year when it looked like #textmate 2.0 was coming soon? Good times… — @‪invalidname‬

Here it is, your moment of irony: Microsoft Word doesn’t recognize the word “cruft.” — @‪petdance‬

Now there’s fame... search for “programmer” on Wikimedia commons, @pragmaticandy is in top 20 images (and 1st real human!) — @‪jlangr‬

We are counting down the Top 100 Clocks You Forgot to Reset. Coming in at 98: your car! — @‪scottdavis99‬

New Rules

OH: “All task cards found on the floor go straight to the Done column.” — @‪staffannoteberg‬

I officially declare that anyone who works with coffeescript/backbone and says lisp is confusing has no valid argument... — @‪abedra‬

The most important piece of information in a requirements document is the phone number to the person who wrote it. #spse2012 — @‪SoftwarePassion‬

“General Nuisance” should be in the official listing of career codes, so we can put it in official documents. — @‪tottinge‬

“If a project team can eat more than two pizzas, it’s too large.” http://bit.ly/FQJlpY — @‪staffannoteberg‬

It doesn’t have to look or behave like ActiveRecord. Great advice for first-time Ruby library authors or greatest advice? — @‪therealadam‬

Sometimes a detour is the best destination. — @‪PragmaticAndy‬

The News

Disappointment that Apple didn’t spend their billions on your pet idea is the new disappointment that Apple didn’t ship your pet feature. — @‪therealadam‬

“Type on retina is *too* crisp” is the new “audio CDs sound sterile.” — @DirkWeber

Skeumorphism is the new flash website. #withintro — @kump

HTML5 is the new 42. — @danivalentin

Short-term memory loss is the new short-term memory loss. — @pragpub

Who Are Those Guys?

They’re not all guys. Also, we have to confess that we cleaned up their punctuation and stuff a little. OK, who they are: Chris Adamson, Jurgen Appelo, Aaron Bedra, Scott Davis, Alan C Francis, Brian P. Hogan, Andy Hunt, Adam Keys, Matt Kump, Jeff Langr, Andy Lester, Brian Marick, Staffan Nöteberg, Tim Ottinger, Software Passion, James Roper, Michael Swaine, Daniella Valentin, Nik Wakelin, and Dirk Weber. You can follow us at www.twitter.com/pragpub.

Meet the Team

Development Editor Kay Keppler

Each month we profile a member of the Pragmatic Bookshelf team. This month we get to know development editor Kay Keppler.

Kay Keppler, Development Editor

Kay Keppler has covered technology and business as a writer and editor for more than twenty years. She started as editor of AI Expert, where one of her authors was working on a (neural network? Bayesian network? chaos theory? Boolean camouflage? it was all Deeply Secret, funded by all that DARPA money) system for cars so they could speed down the freeway in bumper-to-bumper traffic at seventy miles an hour, going where passengers needed to go but without drivers and without hitting anything.

She’s pleased to see that that research has paid off in cars that can parallel park themselves, because parallel parking probably causes more fender benders in the long run than freeway cruising. However, she’s pretty good at parallel parking herself, so she feels a bit like she’s been outsourced. By a Ford. And a Prius.

From artificial intelligence she moved over to Java, where she was editor of Java Pro magazine. That was fun, too. Bill Joy, James Gosling, Sun Microsystems. JavaOne, audience research, startups. Then it got big, went broke, got sucked up by Oracle. So then Oracle happened.

Along the way Kay also exercised her fiction writing skills, and has published several novels in various genres. The latest is a space opera, Zero Gravity Outcasts.

After Oracle, she was looking for something to do that would be fun and useful for developers. Susannah Davidson Pfalzer—a former colleague from the Java Pro days called her—and told her that the Pragmatic Programmers were looking for a few excellent editors. And so she hooked up with “the best—not to mention the most fun—book publishers in the industry.”

And the rest, as they say, is history.

Email: kay@pragprog.com

Personal Website: www.kaykeppler.com

Technical Blogging

An Interview with Antonio Cangiano

by Michael Swaine

We talk with the author of Technical Blogging about why and how technical people shpould blog.

I’ve been blogging since before we knew what to call it. I found early on that the act of putting down brief thoughts about the technical news of the day—or week—gave me the discipline to keep on top of developments and to constantly be digging below the surface of what I was reading. Although it looked like publishing, it worked like research.

In recent years, though, my habit of blogging has been more honored in the breach than in the observance. I was microblogging and publishing my observations in so many forms that I had lost connection with why I blogged to begin with. Still, I knew how useful maintaining a blog has always been to me, and I wanted to get back to regular blogging. So when I heard that blogging guru Antonio Cangiano was writing a book on technical blogging, I knew I wanted to read it.

As it turned out, I got a chance to read it many times, when I became the editor of Technical Blogging.

All of which is by way of warning you that I am not an unbiased observer of this book. And also by way of introducing Antonio Cangiano, Software Developer and Technical Evangelist at IBM for the Toronto Software Lab, author, and all-around nice guy. –Mike

ms: Hi Antonio. Thanks for taking the time to talk with me about technical blogging.

ac: My pleasure, Mike.

ms: Let’s start with the title. Why Technical Blogging? How is that different from just blogging?

ac: It’s true that much of what a blogger does is the same regardless of the subject matter they write about. But there are some special considerations to take into account when the blog is run by a professional for the purpose of sharing his or her knowledge and skills with a technical audience. That blogger’s experience will be different from the experience of a person who runs a personal blog about their cute pet with the purpose of sharing pet photos with their friends and family. 

I called this book “Technical Blogging” and not just “Blogging” for two reasons.

First, because it addresses the challenges and needs of a blogger trying to write for a technical audience. How do you embed code and mathematical formulas? What kind of headlines work online in the technical world? How do you promote your content within a stereotypically anti-marketing crowd? How do you leverage your blog to advance your career, business, or open source projects?

Second, the title signals that my intended readers are programmers, startup founders, and other technically-minded people who don’t need a “for dummies” introduction to blogging. I don’t skip any steps in my roadmap to successful blogging, but I don’t assume that the reader is computer illiterate either.

ms: Can you give us a specific example of that?

ac: Sure. A generic book about blogging might spend a chapter teaching you what a domain name is and why you need one. What I do is to focus on the thought process involved with finding and obtaining a great domain name, its impact on SEO (Search Engine Optimization) and branding, when to use a subdomain if you’re blogging to promote a product or startup, and so on.

Most of my examples are also drawn from the programming world, because I wanted technical readers to feel at home and to be better able to apply the advice to their own blog.

Blogging is blogging, but what I tried to create was a laser-focused, to-the-point handbook crafted specifically for techies. You can use it to make your pet famous on the web, but that’s just a side effect. (Laughs.)

ms: PragPub readers are clearly part of your target audience. But could you expand a little on why software developers need to blog? What will it do for them?

ac: Blogging can act as a conversation starter or a megaphone. This makes blogging a powerful tool for individual developers who are interested in connecting with the larger development community, as well as an excellent (and ethical) tool for self-promotion. Blogging can turn careers—and even lives—around. I can attest to the effects it’s had on my own life. I got my job at IBM thanks to blogging, and I earn a few thousand dollars extra each month thanks to my blogs. Blogging has allowed me to build—and then leverage—my online influence to launch projects like AnyNewBooks.com, which now has tens of thousands of users.

But it’s not just about money. If you do it right, technical blogging lets you tap into a large audience of like-minded professionals, and once you have that kind of audience, there are very few limits to what you can do with it.

ms: For example?

ac: As a developer you can advance your career by establishing yourself in the collective mind as an expert on the subject you’re blogging about. I constantly receive job offers from great companies who discovered me online thanks to my programming blog. If you’re consulting, it’s a prime tool to find new clients and command higher rates. If you write books about programming, you can promote them through your blog. If you run a startup, blogging can help you market your product and succeed in popularizing it.

But aside from all these potentially money-making benefits, there are also many overlooked nonmonetary benefits, like making friends, networking with the top guns in your field, improving your communication skills (which in turn also make you a better programmer), and enjoying the act of teaching others.

ms: I know I’ve always found blogging to be a great opportunity to learn.

ac: It is. As you share your technical knowledge with others, you quickly discover the shortcomings of your own understanding of a given subject and you’re forced to research certain topics more, which in turn leads to a greater sense of clarity and understanding of that subject. You also learn from your commenters and other bloggers that you interact with, especially since some will correct you and others will contribute additional information on top of what you said. I recently wrote a blog post that goes a bit more in depth on such benefits.

ms: The rise of social media and microblogging tools has led some people to proclaim that blogging is dead. Clearly you don’t agree.

ac: Absolutely not. Every month millions of new blogs are created. Blogging has simply become a more mature medium over the past few years. These days it’s easier to try your hand at blogging, and it is more widely adopted. Blogging may grab fewer headlines than it used to, but that’s just because it no longer has that novelty factor. It’s become a well-established medium unto itself. It’s still arguably the best option for publishing long-form content on the internet and reaching a wide audience.

ms: But aren’t there alternative ways to reach people these days that compete with blogging? Microblogging is, if nothing else, a hot buzzword. And I’ve heard people say, if you want to know about my work, it’s all there on Github.

ac: Twitter, Facebook, and other forms of microblogging certainly have their place. However social media platforms are generally complementary to blogging, and not a replacement for it. Can you really write a tutorial on your favorite technology at the rate of only 140 characters at a time? I’d rather publish well thought out content on a blog, and then use Twitter, Facebook, and others to promote my articles and let my followers and online network of contacts know about it.

I think Github is fantastic, but it would be naive to think that it’s all you need to promote your work effectively. Developers tend to be allergic to marketing, so the idea of letting code speak for itself is very appealing. In the real world, though, promotion is an important part of being a successful, well-known developer.

The ideal scenario is to have great Github code out there, and use your blog to point more people toward your Github profile, to let them notice your work. That way, Github complements blogging, but, again, does not replace it. Of course I’m not talking about people who host their blogs on Github.

ms: Although you don’t deal exclusively with WordPress in the book, it does have a strong WordPress focus. Why is that?

ac: WordPress has established itself as a mainstream standard when it comes to blogging. It’s not the only solution available by any means, but it allows you to quickly set up a customized blog that looks and feels like it’s your own. There are a lot of plugins that let WordPress do all sorts of things you may want or need to accomplish, and likewise there are countless WordPress themes (free and otherwise) to choose from.

It’s not perfect. You can object to WordPress’s PHP underbelly, for one thing. But if you are serious about blogging and don’t want to spend all your time writing custom code for your blog engine, using a widely adopted solution has its advantages.

The ecosystem around WordPress is also huge, so it’s quite easy to find designers who are familiar with it. And there are hosting companies that specialize in hosting WordPress for you. As a developer, you may not need this option, but it’s definitely nice to have the choice.

In the book I do provide guidance for users of other systems, such as Blogger, and I mention more esoteric choices like Jekyll and Octopress throughout the book as well. However, knowing that I’d be directing a large audience step-by-step, I opted to go deep with what is, without a doubt, the default (and perhaps best) choice for most technical bloggers.

ms: Let’s get to some examples. Can we talk about a few technical blogs that you think really do it right? I happen to like your own programming blog, Zen and the Art of Programming, but besides that?

ac: Yes, I’d like to describe four examples, two from individuals, and two from startups: Ilya Grigorik’s Blog, RubyInside, The KissMetrics Marketing Blog, and Signal vs. Noise.

ms: Sounds like a good variety of types of blogs. So, taking them in the order you named them, what do you like about Ilya’s blog?

ac: Ilya’s blog is the perfect example of what an individual developer’s blog can be. Ilya doesn’t publish for the sake of publishing, and doesn’t indulge in gossip. Each article on his blog is a more or less in-depth tour of some cool new technology. By reading his blog his visitors can always learn about something new and interesting, and above all how to apply these new concepts to their own projects.

In exchange for his effort, Ilya managed to significantly raise his profile within the development community. It’s not a stretch to imagine that his startup acquisition by Google was at the least facilitated by his popular blog appearing on their radar.

ms: I don’t think you mentioned that as one of the reasons to blog: to be acquired by Google. OK, next? Peter Cooper’s RubyInside?

ac: RubyInside is a news site about a specific niche. Peter Cooper managed to create a must-read resource for anyone who’s interested in Ruby or Rails programming.

ms: A blog as the go-to news site for some niche is a big challenge, though.

ac: Absolutely. This type of blog is demanding and requires a constant stream of new content, but news site blogs can be extremely useful to readers, and as a result can bring a great deal of influence to their authors within the niche they’re covering.

ms: And has for Peter, I’m sure. How about KISSMetrics?

ac: KISSMetrics’s blog is a startup blog. I like what they are doing because they don’t limit the blog to the promotion of their own products. Few people would be interested if they went that route. Instead, they aim to attract the right audience with a blog that’s ridiculously useful to anyone who’s interested in online marketing and web analytics.

Yes, you’ll find the occasional reference to their products, but above all, they too have created a must-read resource. Only this one is not aimed at developers interested in improving their craft and knowledge of a specific technology, but rather at businesses and startup founders interested in marketing their products online. And it does a great job of serving the interests of that audience.

ms: Your fourth example is familiar, I’m sure, to many of our readers.

ac: 37signals created an empire in no small part thanks to their blogging efforts. They are an extreme example of what a startup can accomplish by blogging. The team at 37signals uses their blog to talk about design, usability, business and other topics that are of interest to developers and other startups. Most of their posts are interesting and thought-provoking.

ms: They are that.

ac: Unlike the other blogs I’ve mentioned, they spice things up by not shying away from controversial and confrontational approaches.

ms: OK, you’ve described four very different technical blogs, all successful. So what’s the common thread? You like all these blogs, and you’re not alone. Is there one thing that makes them all so good?

ac: There is a common pattern. All four of these blogs clearly know who their audience is and consistently provide that audience with the type of content they crave. They tend to focus on a given subject or area, and cover it really well with fresh content. Then they reap the benefits of their efforts.

ms: Indeed. You know, in part what you are talking about is producing great and focused content. But you’re also talking about knowing your audience. And that brings up the subject of marketing. We have to talk about marketing. I understand the visceral negative reaction that word can evoke, especially among technical people. But it’s something that every professional needs to understand, right?

ac: Right. Most people have a natural aversion towards marketing. We immediately associate it with obtrusive advertisement or annoying phone calls from someone trying to separate us from our hard-earned money. But the truth is that marketing is much more than that and can be performed in a non-obnoxious manner. Marketing is a service to the producer/provider and to the consumer.

Marketing can be defined as a process that facilitates the discovery of a given product that satisfies a particular need—taking “product” in the most general sense. It’s not just advertising. It begins with the name you choose to give your product and continues on up all the way to the type of customer care you offer your users.

And developers need to do marketing. It doesn’t matter if you’re trying to make an open source project succeed, or a startup, or simply to see yourself succeed. You need marketing skills. You may have written some really interesting software, but nobody will learn about it unless you actively market it in some capacity.

ms: Or even if people are hearing about your software, you may not be reaching the people who most need it.

ac: Right. Marketing isn’t about broadcasting your message to the world. It’s about getting your message to those who want or need it. And blogging enables you to engage in non-obnoxious, informative, and useful marketing. You are not phoning anyone, and you are not displaying advertisements to those who don’t wish to see them. Instead, you are creating and sharing ideas, knowledge, and content that others may find and consider useful. And in the process, you get to expose your project or profile to the audience you worked hard to attract.

ms: Well, there’s a lot more that we could talk about, but I think I’m just going to thank you now and recommend that people take a look at your excellent book.

ac: Thanks, Mike!

Sand Piles and Software

A Metaphor for Software Development

by Zach Dennis

Zach looks at building software as piling up grains of sand one at a time—and then managing the landslides when the sand piles get too steep.

Imagine that every second you’re dropping a grain of sand onto a table from the same fixed position above. As the sand continues to pile up in a heap, what eventually happens to the pile? It landslides! If you keep adding a grain of sand at a time to the pile, it will continue to pile up into a heap, and then at some critical point another landslide or series of landslides will occur. For as long as you add sand to the pile, the pile continues to grow, landslides occur, and the pattern repeats.

Now, imagine that each grain of sand represents functionality in a software system. As you add more functionality, the system piles up into a heap, and at some critical point in the system a landslide occurs. If you continue to add functionality, the system grows, landslides occur, and the pattern repeats. In this analogy each landslide in software represents a state where the system (either in whole or in part) has attempted to go just beyond its maximum threshold for maintaining structural integrity and sustaining growth. The system is in a chaotic state and the effect is felt throughout.

What’s interesting about software is that functionality is never consistently added to the same spot. This changes the sand pile metaphor slightly; no longer do grains of sand drop from the same fixed position, but instead the position moves in accordance with the area of the system we’re working on. As a result, a single pile no longer builds into a single heap from the start; rather, several smaller piles grow into several heaps over time.

We’re developing a metaphor here, but it’s starting to get complicated. Let’s take a step back and look at what a concrete yet simplified example of this sand pile metaphor might look like in software.

Going Critical

Take a monolithic program that is written in a single file, in which we only have global variables and functions available (no classes, no modules). To illustrate the sand pile metaphor, each piece of functionality we add is akin to dropping grains of sand from a single fixed position. The more functionality we add, the more code we write, the larger our file gets, the more polluted our global name-space gets, the more complicated our program becomes, and the bigger our sand pile gets. Subsequently, as the program grows it becomes more difficult to maneuver about, and adding more functionality becomes more arduous with every addition. This difficulty over time can be expressed as a property of our program, at least in how we’re growing our system. We’ll refer to this difficulty at a point in time as the system’s “critical value.”

Eventually, the program’s critical value reaches a point where functionality cannot continue to be added until something is changed. When the program reaches this point it has grown unwieldy and cumbersome to work with. This point can also be expressed as a property of our program: the “critical state” of the system. The critical state represents the highest point a sand pile can grow to before a landslide must occur. At this point, our ability to continue to grow the program has come to a halt.

In the natural world, when a landslide occurs, it shifts the critical value of the sand pile back down, away from the critical state, but it never actually resets to 0. However, in software, landslides aren’t naturally occurring. We, the developers, have to cause them through refactoring, reorganizing, and simplifying, among other things. This helps bring the critical value down, away from its critical state to where the system can continue to evolve. With the program in an evolvable state, we can get back to adding functionality.

There’s actually an inverse relationship at work here: as the critical value increases toward the critical state, the program’s ability to grow declines.

Back in the 1980’s, Meir Manny Lehman observed this relationship in practice: “As an evolving program is continually changed, its complexity, reflecting deteriorating structure, increases unless work is done to maintain or reduce it.” Lehman’s observation goes one step beyond where we’ve gone, but we’ll get to that shortly.

Most programs today are not nearly as simple or limited as the described monolithic program. Even the simplest mobile and web applications are more complex because of the rich environments, languages, and frameworks available to them. But that’s okay, because understanding how the monolithic example works gives us insight into how this metaphor applies in more complex systems (smaller components being used together to create a larger system); which really means we’re dealing with more sand piles, but in the same sandbox.

Getting Stable

Before we dive into that, there’s another facet of this sand pile metaphor that we should take a second to consider: stability.

We already saw how as the sand pile constantly grows it will eventually landslide. It’s not a matter of if, but when. We’re going to make a few more observations about how we can apply the sand pile pile as a metaphor.

First, a smaller/shorter sand pile represents a less complex system or component in the system.

Second, the larger/taller the sand pile is, the more complex the system or component in the system is.

Third, the flatter the pile, the more stable the system is.

Lastly, the steeper the pile the less stable the system is. And by stable, we are referring to a system that is able to sustainably evolve with new or changed functionality; we’re not talking about bugs in the system (which is an interesting correlation, but outside the scope of this article).

This means that a large system that is very well-factored would be represented by a bunch of sand spread out with no jagged mountains or peaks. On the flip side, a smaller system that is very complex would have several sand piles clumped together looking like a mini-mountain range covering a much smaller surface area.

This isn’t to say that all complexity is bad. You may have complex things in your application that are necessary. However, if the structure and design of your code continues to “deteriorate” as Lehman put it earlier, then you’re going to end up with sharper peaks (you’re getting closer to causing a landslide); whereas complexity that is reduced to its simplest form may be tall but will be round or flat on top of the pile.

Additional complexity and the deteriorating structure of code over time is a naturally occurring part of building software, just as the growth of a sand pile is naturally caused by dropping grains of sand on top of one another. As software is built and grown, all of the observations we’re making with the sand pile metaphor hold true: adding functionality is akin to dropping more grains of the sand. How that sand is distributed is what ultimately determines its size, distribution, slope, and peak. All of these properties are reflected in the software’s overall stability as expressed in its ability to change and evolve and continuously allow growth of the system.

Developers are deeply involved with how the sand piles are formed. We can clean as we go and keep a relatively flat distribution of sand. Sure, there may be some clumps and even some peaks, but if they’re kept to a minimum then our system is likely kept in a stable place for continual growth. Or, we can ignore the impact that comes with each change and hope that it doesn’t catch up to us. If you’ve ever been on, or observed a project which got off the ground at a very rapid pace only to come to a sudden halt, then you’ve likely experienced or seen this.

Managing Landslides

This sand pile metaphor offers a simple and easily understandable way to think about the complex activity of constructing software, both conceptually and visually. It also exposes a facet of software development that is often overlooked: a change of any size in the system can cause a landslide. A landslide indicates that the system is so bad that the team has to stop moving forward in order to rework the system. This can take a significant amount of time and one landslide may likely cause several landslides to occur following it.

In my experience, when teams do this they usually don’t take this clean-up far enough. Instead, they do just enough to keep moving forward again, which sounds very pragmatic, but in reality, they’re taking a highly unstable system, barely making it stable again, only to shortly thereafter be in the same unstable situation. Rather than continuously moving at a swifter pace the team is always moving at its slowest possible pace because of the poor state of the software. This vicious cycle is often detrimental to the entire effort of building the software in the first place.

In his book Deep Simplicity, John Gribbin notes a similarity between the sand pile model and earthquakes saying that “just as in the way real earthquakes of any size can be triggered by stimuli of any size, adding a single grain of sand may cause one large avalanche, or a series of small avalanches, or just leave the new grain of sand delicately balanced on the pile.”

Admitting that any change, no matter how small or big, could cause our system to reach its critical state may be tough to swallow, but that doesn’t make it any less true. Understanding this may afford us the humility to accept that we’re better served by curating and caring for our systems as we grow them, much like a gardener with their garden. This isn’t about seeking perfection in our systems, but rather keeping our systems in a constant state of stability that lets us continuously and consistently evolve the software we build in order to provide value to its users and its stakeholders for its lifetime.

How’s the landscape of your software?

For more information on the origins of the sand pile model we’re using as a metaphor please refer to the work done by the physicists Per Bak, Chao Tang, and Kurt Wiesenfeld as they explored the behavior of complex systems on the edge of chaos. (I spoke on the same topic recently here.)

Zach Dennis is a co-author of The RSpec Book and a co-founder and fellow human at Mutually Human Software, an expert custom software strategy and design consultancy in Grand Rapids, Michigan. He has been enjoying Ruby for nearly a decade and has contributed to several projects such as Ruby’s standard library documentation, Ruby on Rails, and RSpec. In his spare time, Zach loves spending time with his family, continuously learning, playing music, and running continuousthinking.com.

Send the author your feedback or discuss the article in the magazine forum.

Scala for the Intrigued

XML as First Class Citizen

by Venkat Subramaniam

Scala handles well-formed XML syntax as regular language syntax. But it goes much farther than that in its support of XML as a first class language citizen.

Scala is a nice language, even for something as sinister as XML processing. Scala makes dealing with XML easy and fun. Let’s explore the XML-related facilities that Scala offers in this eighth part of the series.

We’ll start by creating a small XML fragment in code.

| val greetings = "<greet>hello</greet>"
| println(greetings) //<greet>hello</greet>

The code prints the XML content, but on closer look you discover we wrapped the XML in a String. That’s familiar: most languages contain XML in strings. No wonder XML behaves strangely. How would we behave if constrained that way?

Scala treats XML with respect. It’s given a first class citizen status. So in Scala you can write the above as:

| val greetings = <greet>hello</greet>
| println(greetings) //<greet>hello</greet>

That’s it, no shackles. Scala handles well-formed XML syntax as regular language syntax. We can initialize and assign variables with raw XML content much as we’d assign integers or double values.

If you’re curious, ask Scala what it thought of the XML value you assigned. It politely replies with the type it inferred for the variable.

println(greetings.getClass) //class scala.xml.Elem

The Elem class represents an XML element. You can query (or interrogate) this instance for more details about the document.

| println(greetings.label) //greet
| println(greetings.text) //hello

You can even use the pattern matching facility you saw in the previous article in this series.

| greetings match {
| case <greet>{msg}</greet> =>
| println("found " + msg) //found hello
| }

The pattern matching syntax is quite helpful for extracting contents out of XML documents. This built-in capability of the language minimizes the dependency on third party parsers when working with XML in Scala.

In this example, if the greetings object contains an XML document with root element <greet></greet> the match binds the msg variable to the children nodes of this root element.

We can also use XPath query to access the contents of the document. In XPath you generally use a forward slash to get a matching child and double slash to get all matching descendants. But these two conflict with a Scala operator and the syntax used to create comments. Scala instead uses backslash and double backslash, respectively, for these two XPath operators, as in the next example.

val message = <message priority="urgent">avoid ceremony</message>

| println("Received " + message \ "@priority" +
| " message: " + message.text)
| //Received urgent message: avoid ceremony

To access the value of the priority attribute of the element we used the backslash operator and prefixed the attribute name with an @ symbol. The @ prefix is used to indicate attribute names in XPath queries. Drop that symbol if you’d like to refer to a child element instead of an attribute.

The XML documents we used so far had only one element. Let’s see how to parse a document with more elements. Let’s work with an XML document that has stock prices and tickers:

| val stocksAndPrices =
| <stocks>
| <stock symbol="AAPL">302.15</stock>
| <stock symbol="GOOG">606.20</stock>
| </stocks>

Let’s extract the symbols and their prices.

| stocksAndPrices match {
| case <stocks>{symbolAndPrices @ _*}</stocks> =>
| println("Found " + symbolAndPrices.size + " children")
| //Found 5 children
| }

The stocks element has more than one child. We want to gather all its children. Instead of a simple {msg} we used before, we use _* to gobble up all the contents between <stocks> and </stocks>. Using symbolAndPrices @ _*, we asked Scala to bind the children nodes of the element to the value symbolAndPrices.

The symbolAndPrices is bound to an ArrayBuffer that holds the children of the element. Scala reported seeing five children; that includes the two stock children plus the text nodes before, after, and in between these two elements.

We don’t care about those empty text elements. Our focus is on getting the ticker symbols and prices. We can loop through this collection and at the same time extract the content.

| stocksAndPrices match {
| case <stocks>{symbolAndPrices @ _*}</stocks> =>
| for(symbolAndPrice @ <stock>{price @ _}</stock>
| <- symbolAndPrices) {
| println(symbolAndPrice \ "@symbol" + " : " + price)
| }
| }
| //AAPL : 302.15
| //GOOG : 606.20

In the for expression we asked Scala to iterate over the elements of the symbolAndPrices ArrayBuffer and only give us the stock elements. We indicate with the {price @ _} that we’d like to match any content between the start and closing tags and bind it to the price value.

Instead of using a match and then the for expression, you can directly use the XPath query to extract all stock children from the document and make the code even more concise.

| stocksAndPrices \\ "stock" foreach { symbolAndPrice =>
| println(symbolAndPrice \ "@symbol" + " : " + symbolAndPrice.text)
| }
| //AAPL : 302.15
| //GOOG : 606.20

A combination of XPath queries, \ and \\, and accessing the text property of Elem took care of the processing.

If you know the structure of the document, then by using a combination of pattern matching and XPath queries you can easily extract the contents of the document. If you want to navigate arbitrary document structure, then use the classes provided in the scala.xml package to which the Elem class belongs.

We’ve now seen how to get contents out of an XML document. Scala also makes it easy to create XML documents. You don’t have to deal with unwieldy print statements to produce the desired output.

Given a list of ticker symbols, let’s see how we can create an XML document of the tickers and their prices. Let’s define a sample list of tickers and a function to go out to Yahoo and fetch the prices for each stock. (You’ve see the code to fetch the price in an earlier article in this series.)

| val tickers = List("AAPL", "AMD", "CSCO", "GOOG", "HPQ",
| "INTC", "MSFT", "ORCL", "QCOM", "XRX")

| case class StockPrice(ticker : String, price : Double) {
| def print = println("Top stock is " + ticker +
| " at price $" + price)
| }

| def getPrice(ticker : String) = {
| val url = "http://ichart.finance.yahoo.com/table.csv?s=" + ticker
| val data = io.Source.fromURL(url).mkString
| val price = data.split("\n")(1).split(",")(4).toDouble
| StockPrice(ticker, price)
| }

The getPrice function takes a symbol and returns an instance of the class StockPrice with the ticker name and the price obtained from Yahoo webservice.

Let’s see how to create an XML document of this information. In much the same way you can place XML into Scala code, Scala also allows you to intermix Scala code within XML. You must ensure that the code you place within the {} block produces well-formed XML fragments for this to be meaningful.

| def stockXMLFragment(ticker : String) =
| <stock ticker={ticker}>{getPrice(ticker).price}</stock>

The stockXMLFragment function takes a ticker name as parameter and produces an XML element of the format <stock ticker="symbol">price</stock>. The price is obtained with a call to the Yahoo webservice via the getPrice function.

It was easy to place the data value directly into the XML element using the {} syntax. In the case of the price, Scala will place the value as a simple text child of the element. For the ticker name, Scala will automatically wrap the value between double quotes for the attribute.

We now know how to create an XML element fragment for a given ticker symbol. Let’s use this method to create the entire document for all the ticker symbols on hand.

val stockDocument = <stocks>{tickers map stockXMLFragment}</stocks>

Scala’s conciseness and expressiveness shines yet again here. When you call tickers map stockXMLFragment, Scala passes each ticker symbol in the tickers collection to the stockXMLFragment function and collects or gathers the XML elements. The collected elements become the children of the root element <stocks></stocks> and get bound to the value stockDocument. Let’s print the XML document produced by the above code.

| println(stockDocument)
| //<stocks><stock ticker="AAPL">599.34</stock><stock ticker="AMD">
| //8.03</stock>...<stock ticker="QCOM">66.29</stock>
| //<stock ticker="XRX">8.21</stock></stocks>

The output you see when you run the code will depend on the market conditions at the time of the call, but the structure of the XML document is set in our Scala code.

You learned about the XML processing capabilities of Scala in this article. This is a good opportunity to apply Scala on your projects. If you have a Java project that does significant XML processing, you can replace just the parts dealing with XML using the above techniques.

Dr. Venkat Subramaniam is an award-winning author, founder of Agile Developer, Inc., and an adjunct faculty at the University of Houston.

He has trained and mentored thousands of software developers in the US, Canada, Europe, and Asia, and is a regularly invited speaker at several international conferences. Venkat helps his clients effectively apply and succeed with agile practices on their software projects.

Venkat is the author of .NET Gotchas, the coauthor of 2007 Jolt Productivity Award winning Practices of an Agile Developer, the author of Programming Groovy: Dynamic Productivity for the Java Developer and Programming Scala: Tackle Multi-Core Complexity on the Java Virtual Machine. His latest book is Programming Concurrency on the JVM: Mastering Synchronization, STM, and Actors.

Send the author your feedback or discuss the article in the magazine forum.

The Pragmatic Defense

Making Defects Easier to Find

by Jim Bonang

Jim shows how to write methods with built-in defenses that allow you to quickly find the fault underlying a failure.

Chess grandmaster Vladimir Kramnik famously used the Berlin Defense in his victory over Gary Kasparov in 2000. Such standard chess openings employ a combination of moves that strengthen a player’s defensive posture and provide a sound foundation for the attack. Novice players often neglect such defensive techniques, a failing immediately apparent to more experienced opponents. As programmers, we too can neglect our defenses, allowing defects to gain the upper hand. And defects wreak havoc: effort is devoted to eliminating errors rather than creating new functionality, schedules slip, projects are canceled. No opponent shows less mercy.

However, several mutually supportive software development techniques, employed systematically, much like a standard opening in chess, will shore up our defenses.

You’re likely familiar with many of these techniques already; they include coding idioms, guidelines and processes:

Boolean Return Values for Methods

Single Exit Points for Methods

Exception Containment (where exceptions are contained within method boundaries and provide useful point-of-failure diagnostics)

Logging (with descriptive error messages and suggestions for remediation)

Design by Contract

Method Preambles—source code comments specifying method interfaces that allow automatic generation of documentation

Unit Testing and Test Driven Development

I’ll illustrate how you can weave these techniques together to form a defense-in-depth against defects that I call the Pragmatic Defense (apropos, as several techniques are drawn from The Pragmatic Programmer).Your defenses will be in place as you write your code, helping you keep defects at bay—even in the most stressful of circumstances.

Some time ago, during the last leg of an all day job interview, my potential employer assigned a programming problem in C++ to parse an English language text file and report various statistical information on its content. With the clock ticking, I attacked the problem—and, under the watchful eye of the examiner, ignored my defenses, making a subtle, and fatal, coding error. I could see the failure in the program’s output when running initial tests and began to hunt for the fault. I backtracked, stepping through the code. Nothing. The examiner interrupted to deliver the 15 minute warning. Still nothing. The distance from failure to fault was too great; I couldn’t isolate and remove the defect in time, ending an excellent opportunity. Could employing the Pragmatic Defense have prevented this? More importantly, can it help your software development efforts? Yes—by assisting you in quickly isolating the defects that underlie observed failures.

Let’s look at each of the constituent techniques of the Pragmatic Defense and how they work together.

Boolean Return Value and Single Exit Point

We’ll start with the simplest techniques—Boolean Return Value and Single Exit Point—and apply them to a C++ method. Here’s an outline of our C++ method.

| bool CLaunchController::goLaunch() throw() {
| bool bSuccess = false;
| try {
| // Check Preconditions here ...
| // Method Body
| if(false == goBooster()) {
| // throw exception
| }
| if( false == goGuidance()) {
| // throw exception
| }
| //...
| // Check Postconditons here ...
| // All has gone well, return true.
| bSuccess = true; // GO for Launch
| }
| // Catch specific exceptions here ...
| catch(...) {
| // Log exception
| }
| return bSuccess; // either true or false (GO or NO GO)
| }

With the Boolean Return Value idiom, a function either works or it doesn’t. You may remember watching the tense scenes in NASA’s Mission Control (or perhaps have watched the movie Apollo 13) when Gene Krantz queries the flight controllers for a “Go, No Go for Launch” [Krantz, Gene. Failure is Not an Option, Simon & Schuster, 2009, p. 180]. Either all subsystems are “Go,” or the launch does not take place (essentially a logical AND over the states of all subsystems). No equivocation, no integer error codes, no complex decisions to make. Each subsystem is either ready or it isn’t. Each controller reports either “Go” or “No Go.” Similarly, you know what’s working and what isn’t within your method, every step of the way. And you know unequivocally whether your method worked or not. Very simple.

While the Boolean Return Value idiom simplifies determining the status of your method, the Single Exit Point idiom simplifies its control flow; the Boolean value is returned from only one point in your method, both in the nominal case and in all error cases. In the nominal case, control flows to the end of the end of the try block, where the return code is set to true to indicate success, then to the return statement. In case of errors, the method still exits from the same point but only after reporting the error in a catch block.

With the Boolean Return Value and Single Exit Point idioms, you’ve laid the groundwork for point-of-failure diagnostics, now its time to start emplacing defenses using Contained Exception Handling.

Exception Containment

The Contained Exception Handling idiom catches all exceptions within the scope of the method, as indicated by the throw() suffix in our C++ method declaration example. A try/catch block encapsulates the body of the method; the exception parameter of the last catch handler, catch(...), catches any exception not caught by any previous catch handlers. Any exceptions thrown within method goLaunch are caught within the method and reported or logged within the method. The method exits from the single return statement at the bottom; if an exception was thrown, the method returns false.

Exceptions have the undesirable characteristics of goto statements [Dijkstra, Edsger. “Go To Statement Considered Harmful,” Communications of the ACM 11 (3), March 1968, pp. 147-148.], and exceptions propagated outside of method boundaries are like long jumps—a type of goto statement considered particularly harmful. Disaster may ensue if exceptions propagated beyond the scope of a method remain uncaught [Sutter, Herb and Andrei Alexandrescu. C++ Coding Standards: 101 Rules, Guidelines and Best Practices, Upper Saddle River: Pearson Education, Inc., 2005, pp. 114-115.]. In the Pragmatic Defense, exceptions are always caught within the method where they are thrown. No exceptions.

Logging

Logging exceptions within the functions where they occur reduces the software “distance to fault”—a phrase borrowed from transmission line service that indicates the distance to a physical discontinuity in a cable from a diagnostic measuring device. (Such devices are based on Frequency Domain Reflectometry.) In software, the “distance to fault” represents the intellectual effort required to find the underlying fault or “bug” from an observed failure. The closer the reported failure is to the actual fault, the faster the fault can be isolated. To minimize this distance, exceptions include descriptions of the failure as well as failure location information, such as file name, line number, thread identifier, process identifier, time, and a stack trace. (Some exception handlers even obtain a screen capture at the time the exception was thrown and a mini-core dump.)

| if(false == goBooster()) {
| // throw exception
| throw dx::CExcept("goBooster() failed", __FILE__, __LINE__);
| }

The custom exception class, CExcept, provides the time, process ID, stack trace, and other diagnostic information in the exception description returned by its what() member function. The exception’s what() method is used by the error logging code within the catch handler. Here, errors are logged using the Apache log4cxx logging framework. (Similar frameworks are available for other languages, such as log4j for Java.) For basic console applications, you may wish to emit the error messages to the standard error using std::cerr.

| bool CLaunchCntlr::goLaunch() throw() {
| bool bSuccess = false;
| log4cxx::LoggerPtr logger(log4cxx::Logger::getLogger("Launch"));
| try {
| // ...
| } catch (dx::CExcept & ex) {
| LOG4CXX_ERROR(logger, ex.what());
| } catch (...) {
| LOG4CXX_ERROR(logger, "An unknown exception has occurred.");
| }
| return bSuccess; // either true or false (GO or NO GO)
| }

Error messages should be as descriptive as possible, indicating not only the source of the failure but its possible cause and any corrective actions feasible.

| throw dx::CExcept("goBooster() failed; O-ring temperature "
| "too low. Postpone launch until temperature is "
| "within acceptable limits.", __FILE__, __LINE__);

Boolean Return Value, Single Exit Point, Contained Exception Handling ,and Logging let you know that a failure has occurred and that the fault is present in the execution path in or before the current method. Design by Contract will allow you to further narrow down the location of the fault.

Design by Contract

A legal contract defines your rights and responsibilities, as well as those of the other party to the contract. Design by Contract [Meyer, Bertrand. Object-oriented Software Construction, 2nd ed., Upper Saddle River: Prentice Hall, 1997, pp. 331-438.] applies this concept to software modules. Rights and responsibilities are expressed as preconditions and postconditions (and also invariant conditions, which we won’t cover here). Preconditions specify entry criteria that must be true to start a procedure. Postconditions specify criteria that must be true upon successful completion of a procedure.

Often, preconditions are limits on the valid ranges of input values, but not necessarily. For example, preconditions may include conditions such as:

A particular process must be running

A socket connection must have been established

A file must exist

An environment variable must be set

These could all be postconditions as well. For example, if a function is supposed to create a file, that the file must exist is a postcondition of that function.

Some languages, such as Eiffel, provide native support for expressing pre- and postconditions. C++ does not, but you can check preconditions before entering the method body. For example, let’s add an input value and impose a precondition for invoking the launch method. There are many criteria that must be met prior to launching a rocket; one is the distance to lightning sources.

| bool CLaunchCntlr::goLaunch(double dNautMilesToNearestLightningSrc)
| {
| bool bSuccess = false;
| try {
| // Preconditions:
| // REQUIRE: distance to nearest lightning source must be
| // greater than 10 nautical miles.
| if(false == (dNautMilesToNearestLightningSrc > 10.0)) {
| std::ostringstream oss;
| oss << "Precondition not satisfied: distance in nautical "
| "miles to lightning source invalid: "
| << dNautMilesToNearestLightningSrc
| << " :value must exceed 10 nautical miles.";
| throw dx::CExcept(oss.str(), __FILE__, __LINE__);
| }
| // Method Body ...

If the precondition is not satisfied, there no point in continuing; it makes no sense to call the remainder of the method (it’s not safe to launch the rocket). An exception is thrown, the failure is logged and the goLaunch method returns false. (A C++ Standard Template Library output string stream is used to construct the exception description.) Reporting the precondition failure helps to isolate the fault. The failure of a precondition may not tell you where the fault is, but it does tell you where it isn’t. There’s no need to spend time debugging the goLaunch method; the problem occurred prior to invoking goLaunch, perhaps in the software’s weather subsystem.

Postconditions, on the other hand, tell you where the problem is when a failure occurs. A postcondition is a condition on a method that will become true when the method completes; a postcondition is what the method is guaranteed to do. If all of the method’s preconditions are satisfied, and the method’s postconditions are not met, the fault lies in this method, nowhere else.

Let’s examine a simple C++ method, takeNote, which adds a note string to a collection of notes. It is supposed to add exactly one note string, but due to a copy and paste error (you’re under pressure), a second push_back method was invoked on the vector of strings in the method body, appending two identical notes. Not the required behavior. The postcondition check will report a failure. The size of the vector on entry to the method is recorded in the integral value ulSizeOld. After the body of the method completes the postcondition is checked; the size of the vector is compared with its original size plus one. Due to the fault, this postcondition will fail; the logging system reports the failure. The fault is easy to find—it’s in this method; the “distance to fault” is short.

| bool CNotes::takeNote(const std::string & strNote) throw() {
| bool bSuccess = false;
| log4cxx::LoggerPtr logger(log4cxx::Logger::getLogger("Note"));
| try {
| // Preconditions
| // REQUIRE: length of input note string greater than 0.
| if(false == (strNote.length() > 0)){
| throw dx::CExcept("Precondition not satisfied; "
| "strNote string empty",
| __FILE__, __LINE__);
| }
| // Postcondition Temporary: Save initial size of vector.
| unsigned long ulSizeOld = this->m_vecNote.size();
| // Method Body
| this->m_vecNote.push_back(strNote);
| this->m_vecNote.push_back(strNote); // Fault, copy/paste err
| // Postconditions
| // ENSURE: size of vector has increased by one.
| if(false == ((ulSizeOld + 1) == this->m_vecNote.size()) ){
| std::ostringstream oss;
| oss << "Postcondition not satisfied: "
| << "vector this->m_vecNote "
| << "size invalid: " << this->m_vecNote.size()
| << " :value should be: " << (ulSizeOld + 1)
| << ", one greater than its size on entry to "
| << "the method.";
| throw dx::CExcept(oss.str(), __FILE__, __LINE__);
| }
| bSuccess = true; // all postconditions satisfied
| } catch(dx::CExcept & ex) {
| LOG4CXX_ERROR(logger, ex.what());
| } catch(...) {
| LOG4CXX_ERROR(logger, "An unknown exception has occurred.");
| }
| return bSuccess;
| }

(You can download the source code for this and other example programs.)

Pre- and postcondition expressions must be free of side effects. If performance is an issue, consider placing the pre- and postconditions within conditional compilation directives, and use them only during testing.

Also, if the pre- and postcondition checks distract you from the essentials of the method, an editor supporting code folding will help to minimize their visual footprint. Alternatively, you can place the checks in separate methods; for example, in C++, precondition checks may be placed within a pure virtual method within an abstract base class that defines an interface.

You would then call the base class method in your implementation to check preconditions, as shown in the following code fragments.

| class INotes { // Interface - Abstract Base Class
| public:
| // Pure virtual method with an implementation. Must be overridden
| // but provides precondition checks.
| virtual bool takeNote(const std::string & strNote) throw() = 0 {
| bool bPreconditionsSatisfied = false;
| try {
| // Preconditions
| // REQUIRE: length of input note string greater than 0.
| if(false == (strNote.length() > 0))
| { // ...

The CNotes class implements the INotes interface; it overrides the takeNote method and calls the INotes::takeNote method to check preconditions.

| class CNotes : public INotes { // Implements INotes interface
| // ...
| public:
| bool CNotes::takeNote(const std::string & strNote) throw() {
| bool bSuccess = false;
| // ...
| try {
| // Check Preconditions by calling base class method
| if(false == INotes::takeNote(strNote)) {
| // ...

But how do you know what the preconditions and postconditions for your method should be? You first need to specify what the method is supposed to do and what inputs it needs, and that information is placed in the method’s preamble.

Interface Documentation—Method Preambles

Every method has a signature, which defines its interface. But the signature alone is not enough. A method must be documented sufficiently so that there is no need for its users to examine its internal implementation in order to use it correctly. When you write the interface documentation for the method, you’re specifying what the method must do, in effect defining its requirements. Such specifications are called preambles and are placed in the C++ header file in which the method is declared. As its author, you’re the first user of this method and the preamble provides the specification for your implementation, so write the preamble before you implement the method body. The preamble for method takeNote is shown below, written to support the Doxygen documentation generation tool.

| /**
| * @brief adds a std::string object containing a note to collection
| * of notes.
| *
| * @param [in] strNote reference to non-empty constant string
| * containing a note to be added to a collection of
| * notes.
| * @return true if successful and false if an error occurred.
| * @pre strNote string must be non-empty.
| * @post the size of the collection of notes to which the note
| * contained in strNote was added must be one greater
| * on successful completion.
| */
| bool takeNote(const std::string & strNote) throw();

Doxygen supports a number of languages, including C++, Java, and Python; it will generate documentation in HTML, allowing convenient browsing, a great convenience for future users of your method.

As you implement your method in accordance with its preamble, you’d probably like to conveniently exercise your precondition and postcondition checks. How can you do this? Through unit testing.

Unit Testing

Your pre- and postcondition checks can be exercised using unit tests. A wide variety of unit test suites conforming to the xUnit architecture exists for major languages, including JUnit for Java, NUnit for C#, and CppUnit for C++. In the example below, I use the Google C++ Testing Framework.

The Test Driven Development (TDD) agile process requires that automated tests be written before the code under test; however, many developers find this difficult in practice. Fortunately, the pre- and postconditions, as well as the preamble, make writing unit tests straightforward. You can write an initial unit test exercising a nominal test case as soon as the preamble to the method is done and the basic outline of the method has been implemented. Your initial test can simply invoke the method and check the return code as shown below.

| // CNote::takeNote Nominal Test Case
| // Add note std::string of non-zero length to collection of notes.
| TEST_F(CNotesTest, testTakeNote)
| {
| CNotes notebook;
| std::string strNote = "Unit Testing and DbC are mutually "
| "supportive.";
| EXPECT_EQ(true, notebook.takeNote(strNote));
| }

The output of the test indicated that it failed its postcondition checks and did not return the expected value (true).

The nominal test case can be used to exercise the code as you fill in the body of the method. Unit tests and the method body can be written iteratively; for example, preconditions can be implemented in the method and then unit tests can be written to ensure that the preconditions detect invalid input; execute the unit test and make sure the expected exception is thrown. The postconditions essentially provide a built-in unit test on the output of the method; there is no need to duplicate the postcondition checks in the unit test code.

Once the body of your method is complete, you’ve coded the postconditions, and you have tests for the nominal test case as well as tests for checking the preconditions, write boundary condition tests, worst case tests, and special case tests [Jorgensen, Paul. C. Software Testing: a Craftsman’s Approach, 2nd ed., Boca Raton: CRC Press, 2002.]. This diverges from TDD orthodoxy, but many special test cases do not become apparent until the body of the method is well along.

You now know all the individual techniques in the Pragmatic Defense. But how do you employ them systematically, especially when the pressure is on?

Damage Control Procedures

The crew of the USS Cole fought throughout the day to control flooding resulting from a massive explosive detonated by terrorists against the ship’s port side as it refueled in the Yemeni harbor of Aden in October of 2000. Despite the forty-foot long gash in the hull, by evening the crew had the flooding and other damage under control, saving the ship. How did they succeed against such odds? Damage control is practiced often in the U.S. Navy, using sophisticated simulators; fires are extinguished, masks donned, holes plugged, structures shored up. Standard processes are followed, familiar equipment is used; and that equipment is immediately at hand and always ready for use. All this so that when a vessel is in extremis, the crew will know exactly what to do, automatically. It works.

As a programmer you must often implement software when in extremis. The circumstances won’t be as dire as those faced by the Cole’s crew, of course, but fatigue, lack of sleep, and even burnout can diminish your ability to write correct code. In these circumstances, your defensive tools need to be at the ready. You also need a tried and true process to follow.

First, ensure that your project’s unit test framework, logging framework, documentation tools, and exception handling are in place. Then, follow these steps when writing a method:

Write the method signature

Write the preamble to the method (in a form compatible with Doxygen or similar tools) in the C++ header file

Implement the outline of the method (outer try/catch block, single exit point with Boolean return value, logging) or paste a standard skeleton of the method body

Do not assign the return value to true at the end of the try block as yet

Write a nominal TDD unit test case to exercise the method

Begin writing the method—iteratively.

Insert tests for preconditions

Write the method body; check return codes of invoked methods and throw exceptions when errors are encountered

When the method is far enough along, write the postconditions. (The method body need not be complete when you write the postconditions but the preconditions must be.)

Execute the nominal test case during development, review any failures in the code and correct them

When a first cut of the method is ready, assign the return code to true at the end of the outermost try/catch block

Add other test cases—invalid preconditions, worst case, boundary value, and special case tests

Shore up the method until all tests pass

The Pragmatic Defense won’t prevent you from making errors, just as the U.S. Navy’s damage control procedures can’t prevent ships from being hit. However, the Pragmatic Defense will help you to find those errors and remove them; it will reduce the “distance to fault.” You’ll still inject defects, but you won’t deliver them. Had I used the Pragmatic Defense while taking the programming test during my job interview, I might still have made that subtle coding error, but I would have been able to find it. Quickly. I implemented a solution to the programming test again, this time using the Pragmatic Defense. That subtle error? Checkmated.

The Berlin Defense gained a great deal of popularity after Kramnik used it in his victory over Kasparov. Perhaps the Pragmatic Defense will gain notoriety on your projects; it’s a great opening move.

Jim Bonang has spent over twenty years developing document management systems, medical device software, command and control systems, mission-planning systems, satellite terminals, compilers and other software systems that mustn’t fail. He has also found himself in U.S. Navy damage control simulators on more than one occasion. Jim can be reached at jbonang@ieee.org. Send the author your feedback or discuss the article in the magazine forum.

Calendar

Author sightings, partner events, and other notable happenings.

Here’s what’s coming up in the next three months:

Author Appearances

Who’s where, and what for.

Apr 10—12, Percona Live MySQL Conference & Expo 2012, Santa Clara, CA

“SQL Injection Myths and Fallacies” and “Full Text Search Throwdown”

Bill Karwin, author of SQL Antipatterns: Avoiding the Pitfalls of Database Programming

Apr 10—12, Emerging Technologies for the Enterprise, Philadelphia, PA

“The CoffeeScript Edge”

Trevor Burnham, author of CoffeeScript: Accelerated JavaScript Development

Apr 17—18, Working Effectively In Geographically Distributed Agile Project Teams, Pleasanton, CA

Public Workshop: “Working Effectively In Geographically Distributed Agile Project Teams”

Johanna Rothman, author of Manage Your Project Portfolio: Increase Your Capacity and Finish More Projects, Manage It!: Your Guide to Modern, Pragmatic Project Management, and Behind Closed Doors: Secrets of Great Management

Apr 17—20, Great Indian Developer Summit, Bangalore, India

Keynote and talks on multiple topics

Venkat Subramaniam, the author of .NET Gotchas, the coauthor of 2007 Jolt Productivity Award winning Practices of an Agile Developer, the author of Programming Groovy, Programming Scala and Programming Concurrency on the JVM

Apr 19–20, Railsberry, Krakow, Poland

“Down the NoSQL Rabbit Hole”

Eric Redmond, author of Seven Databases in Seven Weeks

Apr 20, Vimcasts workshop, Berlin, Germany

“Vim masterclass”

Drew Neil, author of Practical Vim

Apr 21–22, Dynamic Languages Conference 2012, Stockholm, Sweden

“Regex in JavaScript and HTML5”

Staffan Nöteberg, author of Pomodoro Technique Illustrated

Apr 23, Mongo Meetup, Boston, MA

“Mongo Indexing”

Eric Redmond, author of Seven Databases in Seven Weeks

Apr 23–24, Agile Sweden 2012, Stockholm, Sweden

“Inclusion over Integration”

Staffan Nöteberg, author of Pomodoro Technique Illustrated

Apr 23–25, RailsConf, Austin, TX

“The Future of Sass”

Hampton Catlin, co-author of The Pragmatic Guide to Sass

Apr 25–27, Roots Conference, Bergen, Norway

Half-day tutorial: “Ruby for Java People”

Paolo Perrotta, co-author of Metaprogramming Ruby

Apr 27–29, Simple Design and Testing Conference (SDTConf), Houston, TX

Open Space Event

Venkat Subramaniam, the author of .NET Gotchas, the coauthor of 2007 Jolt Productivity Award winning Practices of an Agile Developer, the author of Programming Groovy, Programming Scala and Programming Concurrency on the JVM

April 27—29, Northern Virginia Software Symposium, Reston, VA

Multiple talks on JavaScript, HTML 5, Scala, Concurrency, and automated testing

Venkat Subramaniam, the author of .NET Gotchas, the coauthor of 2007 Jolt Productivity Award winning Practices of an Agile Developer, the author of Programming Groovy, Programming Scala and Programming Concurrency on the JVM

May 1–3, MarkLogic WorldWashington, DC

“Stupid XQuery Tricks and XQuery Plugin for IntelliJ”

Ron Hitchens, author of Getting Started With XQuery

May 3–4, SourceDevCon, London, UK

“Vim–precision editing at the speed of thought”

Drew Neil, author of Practical Vim

May 4–5, New York Software Symposium, New York, NY

Multiple talks on JavaScript, HTML 5, Scala, Concurrency, and automated testing

Venkat Subramaniam, the author of .NET Gotchas, the coauthor of 2007 Jolt Productivity Award winning Practices of an Agile Developer, the author of Programming Groovy, Programming Scala and Programming Concurrency on the JVM

May 8–9, Sao Paulo, Brazil

“Project Portfolio Management”

Johanna Rothman, author of Manage Your Project Portfolio: Increase Your Capacity and Finish More Projects, Manage It!: Your Guide to Modern, Pragmatic Project Management, and Behind Closed Doors: Secrets of Great Management

May 8–12, Agile Africa 2012, Johannesburg, South Africa

“Pomodoro–can you focus for 25 minutes?”

Staffan Nöteberg, author of Pomodoro Technique Illustrated

May 11, PyGrunn 2012, Groningen, the Netherlands

“Optimize and automate your dev environment”

Reinout van Rees, author of the upcoming book about Django

May 18–20, Lone Star Software Symposium, Dallas, TX

Multiple talks on JavaScript, HTML 5, Scala, Concurrency, and automated testing

Venkat Subramaniam, the author of .NET Gotchas, the coauthor of 2007 Jolt Productivity Award winning Practices of an Agile Developer, the author of Programming Groovy, Programming Scala and Programming Concurrency on the JVM

May 21–22, JRubConf , Minneapolis, MN

Keynote

Venkat Subramaniam, the author of .NET Gotchas, the coauthor of 2007 Jolt Productivity Award winning Practices of an Agile Developer, the author of Programming Groovy, Programming Scala and Programming Concurrency on the JVM

May 19–24, Problem Solving Leadership, Albuquerque, NM

“Problem Solving Leadership”

Johanna Rothman, author of Manage Your Project Portfolio: Increase Your Capacity and Finish More Projects, Manage It!: Your Guide to Modern, Pragmatic Project Management, and Behind Closed Doors: Secrets of Great Management

May 22, MarkLogic User Group London, London, UK

TBA

Ron Hitchens, MUGL Founder and author of Getting Started With XQuery

May 23–24, DevSum 2012, Stockholm, Sweden

“Advanced Regex”

Staffan Nöteberg, author of Pomodoro Technique Illustrated

May 28–29, Transitioning to Agile for Test, Stockholm, Sweden

“Transitioning to Agile for Test (Testers, Test Managers, Project Managers and others who are not developers”

Johanna Rothman, author of Manage Your Project Portfolio: Increase Your Capacity and Finish More Projects, Manage It!: Your Guide to Modern, Pragmatic Project Management, and Behind Closed Doors: Secrets of Great Management

May 29–31, FluentConf, San Francisco, CA

“The Promised Land: Untangling Async Spaghetti Code”

Trevor Burnham, author of CoffeeScript: Accelerated JavaScript Development

May 30, Project Portfolio Management, Stockholm, Sweden

“Project Portfolio Management”

Johanna Rothman, author of Manage Your Project Portfolio: Increase Your Capacity and Finish More Projects, Manage It!: Your Guide to Modern, Pragmatic Project Management, and Behind Closed Doors: Secrets of Great Management

June 6–8, Norwegian Developer Conference, Oslo, Norway

Multiple talks related to Functional programming, F#

Venkat Subramaniam, the author of .NET Gotchas, the coauthor of 2007 Jolt Productivity Award winning Practices of an Agile Developer, the author of Programming Groovy, Programming Scala and Programming Concurrency on the JVM

June 10–15, Better Software/Agile Development Practices West, Las Vegas, NV

keynote: “Influence and Authority: Using Your Personal Power to Get Things Done”

Johanna Rothman, author of Behind Closed Doors: Secrets of Great Management Manage It! Your Guide to Modern, Pragmatic Project Management Manage Your Project Portfolio: Increase Your Capacity and Finish More Projects

June 13, YAPC::NA (Yet Another Perl Conference), Madison, WI

“29 ways to get started in open source today”

Andy Lester, author of Land The Tech Job You Love

June 19–22, UberConf , Denver, CO

Multiple talks related to Scala, HTML5, Concurrency, JavaScript, Test automation

Venkat Subramaniam, the author of .NET Gotchas, the coauthor of 2007 Jolt Productivity Award winning Practices of an Agile Developer, the author of Programming Groovy, Programming Scala and Programming Concurrency on the JVM

June 29–30, Utah Software Symposium, Salt Lake City, UT

Multiple talks on JavaScript, HTML 5, Scala, Concurrency, and automated testing

Venkat Subramaniam, the author of .NET Gotchas, the coauthor of 2007 Jolt Productivity Award winning Practices of an Agile Developer, the author of Programming Groovy, Programming Scala and Programming Concurrency on the JVM

O’Reilly Events

Upcoming events from our friends at O’Reilly.

Apr 2—4, whereconf, San Francisco, CA

Where Conference: “The O’Reilly Where Conference is where the people working on and using location technologies come together to explore best practices and emerging trends in software development, tools, business strategies, and marketing.”

Apr 9, Mini TOC Chicago Chicago, IL

Mini TOC Chicago: “O’Reilly Tools of Change presents Mini TOC Chicago, a one day event of conversation focusing on Chicago’s thriving publishing, tech, and bookish-arts community.”

Apr 18, online

Velocity Online Conference: “Velocity, the web performance and operations conference from O’Reilly Media, is the premier technical event dedicated to optimizing every aspect of your company’s website.”

Apr 20, TOC Latin America Buenos Aires, Argentina

TOC Latin America: “Tools of Change for Publishing (TOC) is celebrating its premiere in Latin America. Together with O’Reilly Media and the Feria del Libro de Buenos Aires, the Frankfurt Book Fair is bringing the most important conference on publishing innovation to Buenos Aires, Argentina, for the very first time.”

May 29–31, Fluent Conference, San Francisco, CA

Fluent Conference: “The O’Reilly Fluent Conference is about everything JavaScript. If you’re developing for the Web, desktop, or mobile, knowing the ins and outs of JavaScript and related technologies is critical. Come to Fluent to learn from expert developers who are using JavaScript in all kinds of contexts, to do things that no one ever expected JavaScript could do, and do so well.”

June 25–27, Velocity Conference Santa Clara, CA

Velocity Conference: “Velocity is the best place to learn from peers, exchange ideas with experts, and share what has worked (and equally importantly, what has not worked) in real world applications. The focus is on practical, large-scale web development, presented by experts.”

USENIX Events

What’s coming from our USENIX friends.

Apr 10—13, EuroSys 2012, Bern, Switzerland

EuroSys 2012: “EuroSys has become a premier forum for discussing various issues of systems software research and development, including implications related to hardware and applications.”

Apr 24, Hot-ICE ’12, San Jose, CA

2nd USENIX Workshop on Hot Topics in Management of Internet, Cloud, and Enterprise Networks and Services: “The second Hot-ICE workshop builds on the success of the first workshop last year and seeks to bring together researchers and practitioners working on network and service management in the Internet, cloud, and enterprise domains.”

Apr 24, LEET ’12, San Jose, CA

5th USENIX Workshop on Large-Scale Exploits and Emergent Threats: “Now in its fifth year, LEET continues to be a unique forum for the discussion of threats to the confidentiality of our data, the integrity of digital transactions, and the dependability of the technologies we increasingly rely upon.”

Apr 25—27, NSDI ’12, San Jose, CA

9th USENIX Symposium on Networked Systems Design and Implementation: “NSDI '12 focuses on the design principles, implementation, and practical evaluation of large-scale networked and distributed systems.”

May 11–12, PICC ’12, New Brunswick, NJ

Professional IT Community Conference: “The third annual Professional IT Community Conference (PICC) is requesting individuals who are interested in presenting papers, talks, or participating in panels on any aspect of IT and System Administration.”

June 4–6, 5th Annual International Systems and Storage Conference Haifa, Israel

SYSTOR 2012: “SYSTOR 2012, the 5th annual international systems and storage conference, promotes experimental and practical computer systems research.”

June 7–8, 4th USENIX Workshop on Hot Topics in Parallelism Berkeley, CA

HotPar ’12: “HotPar will bring together researchers and practitioners doing innovative work in the area of parallel computing. HotPar recognizes the broad impact of multicore computing and seeks relevant contributions in all fields, including application design, languages and compilers, systems, and architecture.”

June 12–13, 4th USENIX Workshop on Hot Topics in Cloud Computing Boston, MA

HotCloud ’12: “HotCloud brings together researchers and practitioners from academia and industry working on cloud computing technologies.”

June 12–15, 2012 USENIX Federated Conferences Week Boston, MA

FCW ’12: “Back for 2012, USENIX is combining established conferences and workshops into a week of research, trends, and community interaction.”

June 13–15, 2012 USENIX Annual Technical Conference Boston, MA

USENIX ATC: “USENIX ATC has always been the place to present groundbreaking research and cutting-edge practices in a wide variety of technologies and environments. USENIX ATC ’12 will be no exception.”

Other Happenings

Apr 6

MacOS co-creator Andy Hertzfeld is 59.

Apr 5

Inventor Dean Kamen is 61.

Apr 9

ENIAC co-inventor J. Presper Eckert was born on this date in 1919.

Apr 9

SQLite architect D. Richard Hipp is 51.

Apr 14

Ruby designer Yukihiro Matsumoto (Matz) is 47.

Apr 20

Chief Yahoo David Filo is 46.

Apr 24

Champion of modelessness Larry Tesler is 67.

Apr 28

Mathematician Kurt Gödel was born on this date in 1906.

Apr 30

Information theory pioneer Claude Shannon was born on this date in 1916.

Apr 30

Colossal Cave Adventure creator Don Woods is 58.

Apr 30

The World Wide Web is 19.

May

In May, 1980, Erno Rubik’s puzzle started selling internationally under the name “Rubik’s Cube.”

May 1

2006 MacArthur Fellow Jim Fruchterman is 53.

May 2

Protoblogger Dave Winer is 57.

May 8

jQuery creator John Resig got to age 28 one day ahead of Mark Zuckerberg.

May 9

Red Hat founder Marc Ewing is 44.

May 11

Edsger Dijkstra’s 82nd birthday.

May 14

Zillionaire entrepreneur Mark Zuckerberg is 28.

May 17

Youthful Alan Kay is 72.

May 19

Today is the eleventh anniversary of the opening of the first Apple retail stores. Also, Java daddy James Gosling is 57 today; Theo de Raadt, founding member of NetBSD and founder of OpenBSD and OpenSSH, is 44; SNOBOL creator Ralph Griswold would have turned 78 today; and CP/M inventor Gary Kildall would have turned 70.

May 26

Ward Cunningham is 63.

May 27

PEZ was trademarked on this date in 1952.

May 29

63rd birthday of shareware co-creator Bob Wallace.

May 31

John Kemeny was born on this day in 1926.

June

In this month in 1957, computer science legend Donald Knuth published his first article, “Potrzebie System of Weights and Measures,” in Mad Magazine.

June 1

Tim Paterson, whose operating system made Bill Gates a jillionaire, is 55.

June 8

Tim Berners-Lee is 57.

June 23

Vint Cerf is 69.

June 23

Mathematica is 24.

June 28

Firefox co-creator Dave Hyatt is 30.

Shady Illuminations

The Coalition of Yes

by John Shade

Asked to reveal his philosophy of life, John says “No.”

That figures. The founder of Digg gets snapped up by Google, while the founder of Diss has to go it alone.

OK, I lied. There is no social media company named Diss, and there probably never will be. You couldn’t get funding for a company named Diss. VCs and angels wouldn’t pony up the capital. Those people are enthusiasm junkies. They’d rather be building up than tearing down. They see the glass as full—of potential! They want product names that sound sexy and potent. They go to the net-net for the win-win (FTW-W(tm)). They’d like to buy the world a Coke and fund its company.

Personally, I think no-go is usually wiser than go, that he who hesitates may last, that good news is no news, and that some fool keeps putting water in my whiskey glass. I’d rather hear about what you don’t like than what you do like, because I’m likely to like your reasons for disliking and dislike your reasons for liking.

I like hearing about things that don’t work, I get pleasure from avoiding the unpleasant, and I contradict people all the time. I’m a nay-sayer, and if corporate executives sought my advice, which never happens, I’d advise them to emulate that great nay-sayer, Steve Jobs. Except that then they’d probably emulate his tact rather than his judgement. So on second thought, would I do that? No. Once again, No proves to be the winner. But it’s the winner that loses, because the winning side is the Coalition of Yes.

Yes, there is a Coalition of Yes, and it’s a no-brainer to join.

There are a million reasons to say no, but inventors and investors and other gamblers keep saying yes. Yes requires just enthusiasm and the willingness to ignore all the excellent reasons to avoid change. Yes has many friends, and makes people happy. Unlike no, yes is easy to say, and you don't need a reason.

Yes grabs the power line. Yes takes responsibility with a clueless grin. Yes pulls the blocks out when you’re parked on a hill. Yes steps on the gas. No comes from fear and hunger, like all survival skills, while yes comes from openness and selective attention. The tech world is a world of yes, where “limited only by your imagination” triumphs over basic math.

So yes is the new math. Go figure.

John Shade was born under a cloud in Montreux, Switzerland, in 1962. Subsequent internment in a series of obscure institutions of ostensibly higher learning did nothing to brighten his outlook. He says he’d consider joining the Coalition of No only if they refused him membership. Send the author your feedback or discuss the article in the magazine forum.

But Wait, There’s More...

Coming Attractions

This may be the last page, but that doesn’t mean it’s the end of the conversation. Keep up with what’s going on in the Pragmatic universe by subscribing to our newsletter and drop by the Pub again next month for more Pragmatism. We’ll keep a seat warm and a mug chilled and a candle burning in the window.

Coming Soon in PragPub

Venkat will return with more on the Scala language, and I’m looking at a couple of other language-oriented articles, and beyond that—darned if I know. I’m talking with some good people with some good ideas, but nothing is definite.

Coming Soon on the Bookshelf

These books recently went to print: tmux, Technical Blogging, and Programming Your Home; and Deploying with JRuby by Joe Kutner just went into beta.  

Right. But to really be in the know, you need to subscribe to our weekly newsletter. It’ll keep you in the loop, it’s a fun read, and it’s free. All you need to do is create an account on pragprog.com (email address and password is all it takes) and select the checkbox to receive newsletters.

While you’re waiting for the next issue of the newsletter or of PragPub to come out, you can follow us on twitter at @pragpub, @PragmaticAndy, or @pragdave. Or on Facebook at facebook.com/PragmaticBookshelf. Or email us at michael@pragprog.com.