An Extreme Antipattern for Programming Books

tl;dr: programming book authors: put all the code in the book!

An extreme antipattern for a programming book is “download the author’s idiosyncratic library code from some random URL and figure out how to load it on your system”. No, all code used in the book should be printed in the book itself, so the reader can type it in. The URLs always break. The libraries never load properly. A book should never depend on a URL. If you have a small idiosyncratic library, put it in an appendix. If you have a large idiosyncratic library, rewrite your code to be simpler

I know this is an extreme opinion. But I have looked at a lot of older technical books and those that avoid this bad pattern age well and can still be useful and interesting even decades later

Based on the evidence of the last 15 years, I am almost prepared to go fully to the most extreme “don’t put any URLs in Books at all” position because URLs in actual practice are just that bad.

Author: logicgrimoire

I'm the author of 'Jelec: the White Bear, or, Beware an Encounter with a Raven and his Friends.' For my day job, I work as a technical writer at a software company.

5 thoughts on “An Extreme Antipattern for Programming Books”

  1. This is not an extreme opinion at all, but if we’re being realistic this will never happen. There’s simply not enough money to be made through the sales and publishing alone because the publisher takes it all, and so directing people to a sales funnel is the next logical step.

    One of the worst things industry has done post 1970 is to water down all printed and electronic book matter. Its a blue moon rarity to find decent books that helps you ‘do’ things.

    Whether it is gatekeeping by locking people who are bad at math out of a subject that doesn’t need math to get the gist of what’s going on (i.e. those overly rigorous mathematical teaching approaches, where if you aren’t suffering you aren’t learning) or providing just the bare minimum mixed with other questionable but subtle practices to interfere with learning the material (i.e. how both can be right and wrong at the same time), the incentives are all wrong for there to be any quality with very few exceptions.

    When you look at books printed pre-1970, they cover the material in no nonsense terms, with a focus on doing things, and just enough theory to get by; instead of scientific dogma that gets rewritten as counter-examples are found. For example, electricity and electric theory, pre-1970 books talk in terms of voltage as a concentrated field (as a result of the lacquered wire/insulation isolating the wire from conductors that prevent the charge from bleeding off/dissipating except through certain materials, and current as heat as opposed to molecular orbital theory with electronics and holes alongside the infamous water in pipes analogy, too bad the silent book burnings have lost a lot of these older works over the past 20 years. (i.e. libraries optimize for high circulation titles, older books get sold to 3rd-party resellers who warehouse them until they sell or not (at a premium), after which they are sold or recycled.)

  2. Same issue with blog posts linking to my docs, but nobody takes my advice to not do that. I’m afraid we’re in a very small minority on this issue.

  3. Oh my word, I thought, I was the only one who hates this on books especially tech books, they seem to fall on this strap of putting code on URLS. I hate it and some of my older tech books are useless because they relied more on website that were hosted on Geocities(I am exaggerating), but links don’t won’t I had a just book that had links that were point to sun.com now that Oracle bought it, they are useless,

    Thanks for this valuable information.

  4. There was a time that this was what we did because there were few options. Many of my early books had a code disk (even a 5 1/4″) AND all the code in. Predictably, some people complained about having pages and pages of code. Dr. Dobb’s also resisted that. Our articles always had all the code in the magazine until it all went online anyway, if I recall. It was a big difference from some (but not all) other programming magazines.

  5. I would imagine that that is not a decision (or choice as you say) made by the authors.

    I would find it much more likely that some (potentially non-technical) staff at the publishing house makes that decision, arguing that “all the other authors do it too, it makes the book more beautiful, and its less paper and ink (read: cost) for us”

Leave a comment