21–30 of 83 posts
Just glue an envelope with a CD to the backcover, this is what people were doing before your fancy internets became a thing. But really, if you a writing a book on a modern language, and your code has external dependencies, chances are it will not build 5 years forward, even if there are no URLs directly in the book.
First, if the problem is broken URLs, does it make sense to try to fix that instead of not using them? Some odd blog is likely to (eventually) become ephemeral. What about Github links? How long will they last? That seems particularly appropriate for posting code examples. Are there other repositories on the Internet that can reasonably be expected to last?
Second, extremes in either direction could be avoided. Code snippets to illustrate a point are entirely appropriate. Complete programs (beyond hello.c from "The C Programming Language"), probably not so much. Even in the first case I'd suggest including a link to a program that uses the snippet so the curious reader can see the snippet in context.
Just glue an envelope with a CD to the backcover, this is what people were doing before your fancy internets became a thing. But really, if you a writing a book on a modern language, and your code has external dependencies, chances are it will not build 5 years forward, even if there are no URLs directly in the book.
How long do CDs and DVDs last, anyway?
Blu-ray apparently is even hardier.
Just glue an envelope with a CD to the backcover, this is what people were doing before your fancy internets became a thing. But really, if you a writing a book on a modern language, and your code has external dependencies, chances are it will not build 5 years forward, even if there are no URLs directly in the book.
Is it feasible to attach a usb drive to a book these days?
..but really IMO code samples requiring a non-trivial amount of "framework" source is an anti-pattern on its own. Code samples should be short enough that they can be copied by hand.
How do you update code printed in a book?
If a book can be written in such that it does not need to change, then by all means, carefully proof and test all the code and hard code it into the book.
But that's simply feasible in many cases.
Better a book with some external resources than no book at all?
(Oh, and let's set aside the cases where the links to external resources are done in a horrible, broken, poorly conceived way. That's frustrating, but it's not like a book with no external resources produced by those authors/editors wouldn't still be horrible, broken, and poorly conceived.)
The antipattern here is the physical book, surely?
Why? Literally everything in this article would apply to online books as well, except "type it in" would be "copy and paste"
Was it just me, or did anyone else read the "TL;DR" explaining how to AVOID the antipattern to BE the antipattern?
Accentuate the positive. Eliminate the negative.
Two things come to (my) mind. First, if the problem is broken URLs, does it make sense to try to fix that instead of not using them? Some odd blog is likely to (eventually) become ephemeral. What about Github links? How long will they last? That seems particularly appropriate for posting code examples. Are there other repositories on the Internet that can reasonably be expected to last? Second, extremes in either dir…
Github is a proprietary, closed-source service that makes no promises about keeping things for a long time. And even if they do, at the time convenient for them, they'll send out an email titled "We are changing our ToS", and users will just accept it.
Doing infra work for researches I encounter so much dead and dysfunctional content on Github, it's a meme at this point. This especially applies to popular technologies and proprietary stuff. Popular technologies are pushed to abandon support for older versions due to the mob craving new features, more and faster releases. Proprietary technologies become obsolete very fast because they rarely / never try to solve generic problems. It's usually more expedient to solve a particular problem in some way: it takes less time and effort to do so. But it also makes the solution very brittle, dependent on too many external factors.
So, the things that go bad exceptionally quickly is stuff like Github Actions, Kubernetes, Python. If you see that a Github CI Action didn't run in two years, it's almost guaranteed that it's broken. Same for Kubernetes-related code. Python code has an average shelf life of four years.