Table of Contents
In this post I will share a series of personal thoughts concerning a tendency that can be easily observed when reading most programming books review sites such as Amazon, Kobo, Goodreads and the likes. I called this syndrome The Broken Code Myth, which pretty much summarizes what it's about. These contents have been published for the first time in the ASP.NET Core 2 and Angular 5 book (Chapter 1, page 21) as part of a more general considerations regarding how to deal with programming books: however, they can also work in the form of a stand-alone abstract - with some minor changes.
Introduction
There's something very important that we need to understand when dealing with a programming book: seasoned web developers and eager technical readers will most likely already know that, but it could easily slip under the radar of most novice-to-average readers. Anyone who works in the industry - and most competent readers as well - perfectly knows that the "printed" text goes through a lot of changes and rewrites. Now, when we're talking about a standard book, or even a technical book with lots of theorization and no source code, it doesn't really matter: you would get to read Ngnix instead of Nginx or something like that, which is definitely not a big deal. That's not the case for programming books, or for any technical book containing source code lines: when dealing with these kind of books we should be fully aware of the fact that even a single typo, error or misplaced line of text made by the editors OR by the reader WILL prevent the source code from compile, thus driving the unprepared reader to frustration and distress.
On top of that, a programming book's source code might rely upon a number of different programming tools, external components, third-party libraries and so on; most of them will also require some hardware and software specs to be able to work properly, such as: ODBC drivers, .NET/Java/Android/Phyton runtimes, SQL database engine, third-party tools such as Node.JS & NPM and so on. Now, from the book point of view, these things are meant to work together in a 100% compatible fashion, however they are all subject to changes and updates during the
inevitable course of time: as time passes by, the chance that these updates might come with breaking changes that could affect the way they interact with each other and the project health will increase.
If we sum these three factors - book erratas, reader mistakes and components beaking changes - we can clearly see how fragile such scenario actually is: or, to put it in other words, how high are the chances that something will prevent that source code from working as expected - thus leading the unprepared reader into the depths of the Broken Code Myth.
The Broken Code Myth
In an attempt to minimize the chances that the aforementioned factors will actually occur, most - if not all - programming books do the following:
- Try to prevent book erratas hiring technical editors - often more than one - to double/triple check the source code written by the author.
- Try to counter reader mistakes by publishing a 100% tested and working source code to a freely available online repository such as GitHub or BitBucket.
- Try to address components breaking changes by working with fixed versions/builds of any third-party component through the configuration files and also asking the reader to stick with these specific versions/builds, upgrading them at their own risk.
All of these techniques greatly help to reduce the most common sources of problems: the online repository is by far the most effective of them, as it can also help with book erratas (allowing the author to push fixes in real-time) and components breaking changes, at least to a certain extent (being most library managers under source control as well). However, they cannot handle any possible scenario: there will always be a chance that something will prevent the source code from compile properly.
When something like that happens, the less experienced reader will always be tempted to put the blame on the book itself. The most common reactions are usually a rephrase of one of these three lines (or a mix of them):
"There are a lot of compile errors, hence the source code must be broken!"
"The code sample doesn't work: the author must have rushed things and/or forgot to test what he was writing."
"The code is not updated to the latest version of the software / framework / tools I'm currently using, hence the book is no good".
It goes without saying that such hypotheses are hardly true in the tech book industry nowadays, considering the amount of time that the authors, editors, and technical reviewers of these books are required to spend in writing, testing, and refining the source code before building it up and then making it available on an online repository. Any non-amateur developer will easily understand that most of these things couldn't even be done if there was some "broken code" somewhere. Anyone who works in the industry should perfectly know that there's no way a technical book can even hit the shelves unless it comes with a 100% working source code, except for few possible minor typos that will quickly be reported to the publisher and thus fixed within the online repository in a short while: unfortunately, most reader don't possess such knowledge and are prone to come out with the most simple and intuitive answer: the source code is broken. And that's how their fate is sealed: before they know that, they get sucked into the syndrome.
How to deal with that
Luckily enough, avoiding the Broken Code Myth syndrome is rather easy - at least for the non-novice reader with some basic programming knowledge: the basic immunization recipe is to spend a reasonable amount of time trying to understand the root cause of any compilation error encountered before blaming the book.
More precisely, here's a list of questions that any decent reader should try to answer before anything else:
- Am I using the same development framework, third-party libraries, versions, and builds adopted by the book?
- If I updated something because I felt like I needed to, am I aware of the changes that might affect the source code? Did I read the relevant change logs? Have I spent a reasonable amount of time looking around for breaking changes and/or known issues that could have had an impact on the source code?
- Is the book's GitHub repository also affected by this issue? Did I try to compare it with my own code, possibly replacing mine?
If the answer of all these questions is YES, then the book code (or text) have most likely something to do with the issue: most publishers offers a help-desk service, including direct support from the author, that can be used to address the problem. Most readers ignore the fact that dealing with the issue in such way is definitely the best thing that can be done, as it will bring help to the reader who raised the ticket and also to all fellow readers that will stumble upon that same problem: there's even a chance that the fix will be included in a further edition by the publisher, thus improving the book's contents as a whole. As an author, I have seen all of these things happen a number of times.
Conclusions
Don't get it wrong: any reader who wants to use a newer version of his framework, compiler runtime and/or third-party library is free to do that and should be driven and encouraged do that. More precisely, the main scope of any decent programming book is making the readers fully aware of what they're doing and capable of going on their path, way beyond the given code samples.
However, those who feel they're ready to do that should also be prepared adapt their code accordingly; most of the time we're talking about trivial stuff, especially these days when
anyone can Google out the issue and/or get the solution on help-desk knowledge portals such as StackOverflow. They changed the typings? Then we need to load the new typings; they moved the class somewhere else? Then we need to find the new namespace and change it accordingly; and so on.
That's about it, nothing more, nothing less. The source code will experience aging, as it reflects the passage of time; the developer just needs to keep up with the flow, performing minimum changes to it when required. He can't possibly get lost and blame someone other than him if he chooses to update the environment and fail to acknowledge that he'll have to change a bunch of code lines to make it work again.
Are we implying that the authors are not responsible for the source code of the programming book he's reading? It's the exact opposite: the authors are always responsible. They're supposed to do their best to fix all the reported compatibility issues while keeping the online repository updated. However, the reader should also take his very own level of responsibility; more specifically, he should understand how things work for any development book and the inevitable impact of the passage of time on any given source code. No matter how hard the author can work to maintain it, the patches will never be fast or comprehensive enough to make these lines of code always work on any given scenario. That's why the most important thing the reader needs to understand - even before the book topics - is the most valuable concept in modern software development: being able to efficiently deal with the inevitable changes that will
always occur.
Whoever refuses to understand that is doomed; there's no way around it.
UPDATE: I tried to pull-off a demonstration of the Broken Code Myth syndrome in the following post, by taking some of the best Amazon reviews I received as examples: if you're among those who think that such scenario can be easily avoided I strongly suggest to read it!
