The State of Technical Example Code

While I understand the idea behind leaving out some details in example code in technical books, I just don’t agree with it in general. The reason behind picking up a book on a particular framework, language, or technique is to be able to immerse yourself in some sample code. If the authors opt out by including incomplete examples or relying on you downloading their example code I feel just a bit cheated and frustrated. “Not all code examples from this book will be complete,” is a bit of a cop out when some of the incomplete examples are in the first few chapters where the basic concepts are being introduced.

I learn primarily by example and reinforcement. That means when I crack open a book I expect to be able to type in the examples pretty much verbatim and get them to run successfully after I clean up my ever present typos. Typing in the code helps me learn it, more so than just reading or cutting and pasting it from the author’s examples. Short snippets of code are fine, but if the author bothers to show a real example class it should contain pretty much everything you need to run it or at least have it compile. The last couple of technical books I’ve read seem to assume you’ll just figure out all the stuff they left out like the implementations of 3 or 4 other classes the example depends on.

I have a limited amount of coding time between the daily meeting load, distractions, HR issues, and clearing obstacles for my developers. When I get home and my two young daughters are off to bed I have a few hours a night to possibly go through a technical book. I don’t have time to waste chasing down little details in the examples that were left out or imagining how I setup some example code by inventing an implementation. I realize this approach forces me to go looking for answers and do a lot of experimenting to get some examples to run, but far too much of that is frustration and not learning. I like rapid feedback loops, one of the reasons I enjoy TDD so much. Frustration is pretty much the opposite of what I’m looking for.

No books were named in this rant, but that’s partially because the phenomenon is so commonplace. A good counter example in my recent experience would be Head First Design Patterns. I love that they give full class examples and exercises that are left to the reader. That way I can get the concepts and then enjoy the challenge of the exercises. They of course add a lot of visual interest, crossword puzzles, and inside jokes.