Sample Code on Programming Books Considered Harmful

I am an avid reader of programming books. I think it is important to benefit from the experience of other fellow programmers, and one way of doing this, other than reading other people’s software, is reading books that collect some kind of development experience.

Although it is interesting to read about programming, there is a big downside on programming books: the programming examples that they present.

Coding samples are given on books to exemplify techniques. They can very well perform this task, but they also carry with them several problems that make them a tough sell:

Most code examples are of low quality: one of the reasons for this is that coding samples in books are not directly checked by a compiler. I know that most writers in fact check this before publishing something. But in reality there is no guarantee that between final edition, changes requested by the editor, etc., the sample code will still be correct. Authors and editors try to be careful, but by the very nature of the process there is the possibility of mistakes that wouldn’t be allowed by a compiler.

Sample code is tied to the author’s environment: a very frustrating scene is to open a book on some technique, then type the sample code and find out that it almost works. That is, it compiles, but for some obscure reason it doesn’t perform what it was supposed to do. This is a problem that everyone learning to program has encountered at least once. Probably the main reason is that sample code, by its brevity, is tied to the environment in which the author is working. Most modern programming technologies are too complicated to be reduced like that.

It promotes bad programming habits: The worst habit, which is also rampant on programming forums, is programming by copying and pasting. While it is simple to directly copy and paste a piece of code, it rarely works the way you immagine. You are also making your own code more complicated, and it is just like adding a strange body to your house: you don’t really understand what you are doing.

It always lacks encapsulation: by the very nature of coding samples, it has nothing to do if your application domain. By using such code, you are programming in the authors level of abstraction, not in your level of abstraction. A classic example is someone creating a Windows program using the Win32 or .NET API. The code is usually littered with Win32 or .NET terms. By doing this, you are programming at the level of abstraction of the Windows API: windows, forms, handles, callbacks. Such a programmer is not doing a good job in representing the level of abstraction of the application. The level of abstraction of your code should be based on the elements of your domain, not on windows and dialog boxes. These elements should be encapsulated as part of the objects used by your application.


Conclusion

My advice on this area is: read as many books as you can, but don’t bother using any of the sample code included. Prefer online resources, that are much easier to check. Prefer also the documentation from your vendor, that should be easier to read now that you (hopefully) know how the technology works (if the author did a good job). Use sample code from a book only as a last recourse, but be warned: it may be bad for you.


Further Reading

  • Desing Patterns: this is THE book you can use to start thinking about abstraction at your level, instead of the abstractions others want you to use. This book is has very high rate of ideas per lines of code. Also check this one on the same subject, but much easier to read.

Similar Posts:

About the Author

Carlos Oliveira holds a PhD in Systems Engineering and Optimization from University of Florida. He works as a software engineer, with more than 10 years of experience in developing high performance, commercial and scientific applications in C++, Java, and Objective-C. His most Recent Book is Practical C++ Financial Programming.

7 Responses to “Sample Code on Programming Books Considered Harmful”

  1. Can’t agree more. While I think sample code has it’s uses, space constraints often lead to code that takes too many short-cuts. Not a problem if the reader is familiar with the “right way” to do things, but, unless it’s pointed out, many readers are going to put that sample code into production apps.

    I made that point in a review of PHP and MySQL Web Dev.
    (http://yyztech.ca/reviews/book/php-mysql-web-development), which actually realizes this is the case – and tries to discourage it.

    By Zoltan on May 16, 2009

  2. @Zoltan: it is really rare a case where the author realizes how bad the code is (in the sense that I described in the article). Just making that acknowledgment would make life much easier for inexperienced readers.

    By coliveira on May 16, 2009

  3. But what about programming languages like Java. We can’t just go through all api to start coding. We have to get some idea, in order to get that we have to follow few steps. I don’t say copy and paste but get the logic, practice coding and compare with text book code.

    By james on May 18, 2009

  4. Not sure I agree. Most samples are for illustrative purposes, a way to get a technique, syntactical construct or idiom across to the reader in a terse and finite language.

    The best counter example I can come up with, is to compare the GoF and Head First Design Patterns books. The former makes you fall asleep before you hit page 10, the latter shows you exactly how to apply it with samples throughout the book.

    That’s not to say I haven’t seen bad samples or 1000+ paged textbooks, point taken. But to claim sample code is considered harmful is a bit of a stretch.

    By Casper Bang on May 18, 2009

  5. Several publishers now use live code in book production.

    Aside from that, you’re simply making a huge, sweeping generalization that serves little purpose.

    By Dave on May 24, 2009

  6. The main ones for me are QB, freebasic, & C. I’ve been mlniay programming C on linux lately. I know bits & pieces of many other ones as well. Essentially, the programming language is fairly irrelavent, in my opinion. Programming concepts & problem solving skills carry over to just about all languages and make it easy to pick up new ones.I’m not an aspiring programmer so I don’t really go deep into languages & computer science, just write basic programs that work for me. How’s computer engineering working out for you? I am studying electric engineering myself.

    By Joseph on Dec 12, 2015

  7. I think that having fun with programming is one of the best things you can do with computers. In the 80s there was a lot of support for hobbist programming, there should be more focus on this side of programming. Especially for young kids learning to program in high school, for example.

    By coliveira on Dec 30, 2015

Post a Comment