software

Sample Code on Programming Books Considered Harmful

Bycoliveira May 15, 2009October 23, 2009

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.