Coding Horror

programming and human factors

Following the Instructions on the Paint Can

I was chatting on the phone with a friend of mine a few days ago, and he described a project he recently inherited. It was the work of a half-dozen different developers, who each built their parts of the project in a completely different way with little to no communication between any of them. The code tells the story: you'll find the rank amateur; the pattern-a-holic; the global variable guy.

It's a shame that software developers can't get the kind of basic guidance or training they need to prevent these easily avoided disasters. That's why The Daily WTF is more depressing than funny to me – we see the same classic mistakes day after day. That's the norm! Steve McConnell, in Rapid Development, elaborates:

When I was in seventh grade, my art teacher stressed that any student who followed his instructions would get at least a B; no artistic talent required. He was a 220 pound ex-Marine, and considering he drove that advice home at least once a week, I was amazed at how many 98-pound seventh graders didn't follow his instructions and didn't get at least a B. Judging from their work, it wasn't because they were tormented by glorious, conflicting artistic visions, either. They just felt like doing something different.

As an adult, I often see software projects that fail merely because the developers and managers who work on them don't follow the instructions – the software-development fundamentals described in this chapter. It's true that you can develop software without mastering the fundamentals – sometimes even rapidly. But judging from most people's results, if you don't master the fundamentals first, you'll lack the project control needed to develop rapidly. You won't even know whether you're succeeding or failing until late in the project.

Indeed, simply knowing the fundamentals is a critical differentiator between hobby programmers and so-called professional programmers. And it's not even that complicated. Steve likens it to following the instructions on the paint can:

Suppose you're starting a painting project, and you read the following instructions on the paint can:
  1. Prepare the surface: strip it down to the wood or metal; sand it smooth; remove residue with a solvent.
  2. Prime the surface using an appropriate primer.
  3. After the surface is completely dry (at least 6 hours), apply one thin coat. The air temperature must be between 55 and 80 degrees Fahrenheit. Let dry for 2 hours.
  4. Apply a second thin coat and let dry for 24 hours before using.

What happens if you don't follow the instructions? If you're painting a doghouse on a hot Tuesday night after work, you might only have 2 hours to do the job, and Fido needs a place to sleep that night. You don't have time to follow the instructions. You might decide that you can skip steps 1 through 3 and apply a thick coat rather than a thin one in step 4. If the weather's right and Fido's house is made of wood and isn't too dirty, your approach will probably work fine.

Over the next few months the paint might crack from being too thick or it might flake off from the metal surfaces of the nails where you didn't prime them, and you might have to repaint it again next year, but it really doesn't matter.

What if, instead of a doghouse, you're painting a Boeing 747? In that case, you had better follow the instructions to the letter. If you don't strip off the previous coat, you'll incur significant fuel efficiency and safety penalties: a coat of paint on a 747 weighs 400 to 800 pounds. If you don't prepare the surface adequately, wind and rain attacking the paint at 600 miles per hour will take their toll much quicker than a gentle wind and rain will on Fido's doghouse.

What if you're painting something between a doghouse and a 747, say a house? In that case, the penalty for doing a bad job is less severe than for a 747, but a lot more severe than for a doghouse. You don't want to have to repaint a whole house every 2 years, and therefore you hold the results to a higher standard than you do with a doghouse.

Most of the software projects that have schedule problems are house-sized projects or larger, and those projects are the primary concern of this book. On such projects, the development fundmentals save time. Far from being as rigid as the steps on a paint can, if you know enough about them, they also provide all the flexibility anyone ever needs. Ignore the instructions if you wish, but do so at your peril.

I'm sorry you got stuck with the doghouse, Josh. Here's hoping we can educate the next batch of developers so the next guy after you has better luck.

Written by Jeff Atwood

Indoor enthusiast. Co-founder of Stack Overflow and Discourse. Disclaimer: I have no idea what I'm talking about. Find me here: https://infosec.exchange/@codinghorror