I remember that my copy of Geoff Chappell's "DOS Internals" had a floppy disk with the source code taped into the last page. Still readable after 20 years.
But these times seem over. Today there are too many topics that are not covered by books or don't have proper documentation at all.
Why not? A TL;DR is a summation of the article. The title tells what the article's about.
So just reading the title and the tl;dr would leave one with no actual idea of the antipattern. What if the article was about something for which the imperative voice was an accurate description?
Describing something in the imperative voice doesn't make sense.
Why would you ever say "TL;DR perform this action" instead of "TL;DR performing this action", when trying to describe something that people should not do?
I agree in principle. My (unstated) point though is that when you have a second order solution to a second order problem, it is often worth considering moving up the stack to work out why that is.
I'm reminded of my old (1980s) copy of Tannenbaum's Operating Systems Design and Implementation, which had a _complete_ listing of the Minix kernel as an appendix. I learned a lot from that book, even if I've forgotten much of it in the intervening years. I wish I still had it
I would qualify this by saying yes, put the source code in the book, but only if there is something to learn from reading the code. That used to always be the case, but now there's so much boilerplate required for libraries and frameworks that it's obviously a waste of space to put it there. But if reading and understanding the code is part of the learning process, then yes, it should be inline as part of the experience of reading the book.
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.
A cheap USB drive sells for under $10 and you can seal a book in plastic so I'd imagine it'd be feasible to just add the $5-$10 to the price of the book. People who buy books, especially programming books, generally aren't very price sensitive anyway.
Can we attach an attack vector to the book cover? Sure. I wouldn't let that USB anywhere near my computer if I'd bought it let alone a library copy of it.
I'm with the author on this one. Any code needed to for it be useful should be printed in the book (perhaps complete code in an appendix rather than right there in the chapter). That said I haven't bought a programming book in years.
The universal nature of USB is a huge drawback for its usage for storage.
But well, the trend has been to consolidate anyway. Now even power comes through an universal interface, so you can't use power outlets in places that you don't trust.
These days you could add the source as a large QR code. (by which I mean the actual verbatim code, not a URL)
..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.
I have a guitar instructional book that I've had more than 20 years, just checked out the CD the other day and it's still good. Also I've only mastered half of the exercises in the book so I'm still getting use out of it after all this time.
If programming books still came with CDs (or USB drives), we’d be reading blog posts complaining about that.
I can see the comments now: “Just put it on GitHub! Why do they put it on something physical that I’m just going to lose!?”
Retailers loathe books with extras (CDs, USB, or otherwise) because the rate of issues and problems with returns goes way up. Customers dislike it because they’ll lose the thing. Just put it on GitHub and call it a day.
I could understand some of these complaints if a certain publisher has gone out of business and all of their links were dead or something, but I can’t really get worked up about someone having to clone a repo from the internet to work with code. I’d much rather deal with that than I would keeping track of a physical thing that comes with a book, which I have to stick into my computer.
Linux Format quit shipping CDs with the magazine, oh, about a year ago, maybe. I think some of it is also "shrinkage" (the term in retail in the U.S. for shoplifting + breakage, etc). I liked the CDs for many reasons, one of which was once you open a browser...off you go. However, there are still people in the world who may want to learn but have rate-limited, firewalled, or dodgy Internet. It's like cashless systems that cut out millions of people. [1]
I don't see why it would be a problem with items mailed, except it would add another step for the publisher or distributor. But along those lines it irks me when I subscribe to a print publication that includes digital and after I login the only benefit I get it to read more stuff on the same tracker-loaded, privacy-invading enshitified site.
[1] During COVID I protested vigorously at my church about going virtual for many reasons. One of which was elderly or impoverished members who could not (because of either access or ability) easily access whichever platform was being used. There are so many variations of "works on my system" in the world.
I have many hundreds of tech book PDFs (largely due to Humble Bundle and a Manning subscription) and I’m confident I’ll have no difficulty opening those PDFs far into the future.
With a physical book, code requires extra pages, which drive up the cost, and make the book take up more space (though this can be a positive if your book might look too short otherwise). With a digital book, you can freely include as much code as you want.
How about distributing the "full" book as a docker image where you have both the source and compiled binaries (if relevant) of all the code samples in the book?
I agree that urls for this sort of thing are unreliable and there is some merit in requiring the reader to type the code in manually but how about putting an outrageously complex QR code in the book that you can scan to get a copy of whatever function or class the author is trying to demonstrate?
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.
> That seems particularly appropriate for posting code examples.
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.
> Github is a proprietary, closed-source service that makes no promises about keeping things for a long time.
GitHub doesn’t arbitrarily remove public repos for no reason.
GitHub is extremely unlikely to just disappear overnight.
If people aren’t willing to accept GitHub as a place to host public code in this thread, I think people are just looking for reasons to complain about things rather than looking for a practical solution.
geocities didn't arbitrarly remove public web pages for no reason, yahoo groups didn't arbitrarily remove public files for no reason, and friendster didn't arbitrarily remove public profiles for no reason
until, one day, they removed all of them
hosting information on a centralized website is a viable way to host it for a year or two, or maybe ten. but books have a lifespan measured in decades or centuries. so centralized websites are not suitable
If you print "just the program" (i.e. no dependencies), it will spoil very quickly.
If you print both the program and dependencies, it will live a little longer.
If you print dependencies and the source of the interpreter, it will live even longer.
If you print the interpreter and its dependencies -- even longer.
As you can see, the general problem with languages like Python is extreme reliance on external components. Essentially, Python programmers don't write whole programs, they add a polish on an automobile manufactured by someone else, and then present it as their work... Unsurprisingly, it's hard to ensure one's car's longevity if all they can control is the amount of polish they apply to it.
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.)
Fine with me. (op would still object, though, because their issue is "The URLs always break. The libraries never load properly. A book should never depend on a URL")
I really don't think you read and understood my post.
I thought I made it clear, but I'll try again:
There are two cases.
One, where a book can be written in a self-contained manner, without urls to external resources. As you can see, I am happy with this case (which means you really can't conclude I'm criticizing printing thins in a book.)
And another case where it isn't feasible to write the book in a self-contained manner. In that case, the choice is between a book with urls to external resources or no book at all. OPs blanket stance against URLs in books is short-sighted because the only way it can be realized is to simply have fewer choices of books.
Probably OP should argue that books should have as few urls to external resources as possible, and the subject of those urls should be inherently dynamic and fundamental to the book, and the book should include a credible plan for maintaining the external resources for the useful lifetime of the book (which could be a long time).
it's possible that you didn't understand my counterargument, since your clarification isn't relevant to it
this logic doesn't draw any distinction between code and natural-language text; it's true that it's a somewhat restricted argument against printing things in books, because it doesn't argue against printing 'self-contained' things that 'don't need to change' in books. but it's an argument against printing natural-language text in books to exactly the same extent that it's an argument against printing code in books
ironically, it works much better as an argument against printing urls in books than as an argument against printing code in books. c or c++ or java or perl or javascript printed 25 years ago still works fine, but most urls from 2 years ago are already broken. natural-language text written about the c++ or javascript code 25 years ago is somewhat more likely to have become incorrect than the code is
python is an exception here, since it's been taken over by the sort of fashionistas who wouldn't be caught dead wearing last season's standard library, and are actively taking steps to sabotage backward compatibility
Mine (archived by still in possession) are FreeBSD 6.0 Unleashed and some compendium of Computer Science articles from ACM circa 2004.
>FreeBSD is extremely robust and powers some of the largest internet sites in world including Yahoo!. FreeBSD 6 Unleashed provides complete coverage of everything you need to know to use FreeBSD to its full potential, including coverage of FreeBSD 6.0. This edition includes updated coverage of Apache, MySQL and Sendmail, as well as added coverage of PowerPC support for Macintosh G3 and G4 platforms. This is the most up to date, comprehensive reference on the market covering FreeBSD 6.0.
My copy of 'Programming Perl' is the thickest book on my shelves, narrowly beating out 'The Peloponnesian War' (though the latter is taller, so it's hard to say which is the longer read).
Inside SQL Server 2008 T-SQL Programming is somewhat thicker. In fact, it is about the size of Programming Perl and Modern Perl together--though I must add that Programming Perl lost its front cover a while ago.
I don't think I'd call that an antipattern, tbh. Lots of things did this - I remember our CIO bought us all fancy IDE thingies back in the early J2EE days; I forget what it was, JBuilder, maybe?
Everyone was using Eclipse (or us greybeards sticking to our emacs and ((neo)v)im, by then so we ALL used them as monitor stands.
I got this [1] a few years ago deluding myself into believing that I'll learn a bit from it everyday. Alas, the only way it's useful to me on a daily basis now is as a monitor stand. I remain cautiously hopeful that I'll begin pecking at it someday.
> You should be able to get a few MB on a page easily
A few hundred Kb, maybe, but a few MB seem unlikely.
If I take the best case scenario (no optical aberration, perfect sensor...), my phone has a 48MP camera. We cannot have 48M * 3 colors as those 48MP are after Bayer matrix handling.
We also cannot have more than one bit of information per pixel, due to printing often not having "real" greyscale but some kind of dithering and you don't know for sure how it would interact with your sensor.
So in the best case, 6MB.
But then, you need to add error correction: books prints are not perfect, especially at a sub-0.1mm scale. They are also not perfectly planar as paper is grainy.
And the camera is not exactly at a 0 angle... In the 3 axis. So you would need to have the printed pixels be way larger than the sensor ones to be able to offset this.
And so on.
I explicitly talked about the best case scenario, which would have been "one camera pixel is able to retrieve precisely the information of one printed pixel (or several printed pixels that act as one)"
From there, I simply listed sources of error that would make it worse and words. The only place I could see conflation occurring is when I wrote about "sub 0.1mm" which indeed refers to the printed thing, and correspond roughly to the tolerance that would be needed to achieve millions of "printable" pixels, but even if it's about the printed pixels, it still limits the amount of information that would be stored.
Would you mind indicating where there seem to be confusion according to you? Re-reading it quickly, the comment seems consistent and indicates that both the camera pixels AND the printed pixels would cause issue.
I don’t know, still seems feasible. High quality full page images can be printed at ~2500x3500 pixels per page [1] (random print shop from the internet, but representative AFAICS), and that’s just what printers recommend for human readable images, they can produce images easily to 1200 DPI.
In another example, take the Machine Identification Codes (MIC) tracing dots that basic home printers can produce [2], (I bet the publishing industry could do much better to produce a high density grid.)
These dots have a stated diameter of 0.1 mm, and on an 8”x10” area one could get a grid of 80x25.4x25.4x(1/0.1mm)x(1/0.1mm)= ~5.1M dots.(wikipedia claims larger spacing, but that must be the protocol, printing itself allows for highly precise positioning) And that’s just for one color. Use CMYK (you could imagine a sub-project to design a 8bit color based dot scheme) and compression, and even with ECC losses I can see a few MB of encoded source per page being possible. And writing that decoder would be a great exercise!
One way to make URLs printed in books more durable is to submit them to the Internet Archive and then use the archival URLs to include in the printed book instead (kind of how folks here circumvent paywalls..).
So if you write a book about Python, you should include the full source code to Python as well, right? If you write a book about Java, the full source code to the JDK, and so on. Because if the readers have to download and install that by themselves, the book would not be self contained anymore, URLs may break, etc etc.
Ah, no, programming language runtimes are Ok, no need to include them. But then if you write a book about React, or MySQL, or... well, you get the point.
82 comments
[ 2.8 ms ] story [ 152 ms ] threadBut these times seem over. Today there are too many topics that are not covered by books or don't have proper documentation at all.
So just reading the title and the tl;dr would leave one with no actual idea of the antipattern. What if the article was about something for which the imperative voice was an accurate description?
Why would you ever say "TL;DR perform this action" instead of "TL;DR performing this action", when trying to describe something that people should not do?
Accentuate the positive. Eliminate the negative.
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.
If we can have potato chips that play music[1], we can have a book with built in storage.
1. https://web.archive.org/web/20190516225905/https://www.billb...
I'm with the author on this one. Any code needed to for it be useful should be printed in the book (perhaps complete code in an appendix rather than right there in the chapter). That said I haven't bought a programming book in years.
But well, the trend has been to consolidate anyway. Now even power comes through an universal interface, so you can't use power outlets in places that you don't trust.
..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.
https://www.vistaprint.com/promotional-products/technology/u...
https://www.instructables.com/USB-PCB-Business-Card/
https://hackaday.com/2010/05/25/mass-storage-business-card/
cds are a lot cheaper
Blu-ray apparently is even hardier.
I can see the comments now: “Just put it on GitHub! Why do they put it on something physical that I’m just going to lose!?”
Retailers loathe books with extras (CDs, USB, or otherwise) because the rate of issues and problems with returns goes way up. Customers dislike it because they’ll lose the thing. Just put it on GitHub and call it a day.
I could understand some of these complaints if a certain publisher has gone out of business and all of their links were dead or something, but I can’t really get worked up about someone having to clone a repo from the internet to work with code. I’d much rather deal with that than I would keeping track of a physical thing that comes with a book, which I have to stick into my computer.
I don't see why it would be a problem with items mailed, except it would add another step for the publisher or distributor. But along those lines it irks me when I subscribe to a print publication that includes digital and after I login the only benefit I get it to read more stuff on the same tracker-loaded, privacy-invading enshitified site.
[1] During COVID I protested vigorously at my church about going virtual for many reasons. One of which was elderly or impoverished members who could not (because of either access or ability) easily access whichever platform was being used. There are so many variations of "works on my system" in the world.
I agree that the obsolescence rate has skyrocketed, as a side-effect of always-online development.
Those CDs have a way of disappearing. My local library used to have a lot of tech books that were missing the accompanying CDs.
An anachronism from before the current era, when you can take a picture of text with your phone and tell ChatGPT "transcribe this".
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.
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.
GitHub doesn’t arbitrarily remove public repos for no reason.
GitHub is extremely unlikely to just disappear overnight.
If people aren’t willing to accept GitHub as a place to host public code in this thread, I think people are just looking for reasons to complain about things rather than looking for a practical solution.
until, one day, they removed all of them
hosting information on a centralized website is a viable way to host it for a year or two, or maybe ten. but books have a lifespan measured in decades or centuries. so centralized websites are not suitable
Good point.
> Python code has an average shelf life of four years.
Wouldn't that also be a problem for examples in print?
If you print "just the program" (i.e. no dependencies), it will spoil very quickly.
If you print both the program and dependencies, it will live a little longer.
If you print dependencies and the source of the interpreter, it will live even longer.
If you print the interpreter and its dependencies -- even longer.
As you can see, the general problem with languages like Python is extreme reliance on external components. Essentially, Python programmers don't write whole programs, they add a polish on an automobile manufactured by someone else, and then present it as their work... Unsurprisingly, it's hard to ensure one's car's longevity if all they can control is the amount of polish they apply to it.
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.)
I thought I made it clear, but I'll try again:
There are two cases.
One, where a book can be written in a self-contained manner, without urls to external resources. As you can see, I am happy with this case (which means you really can't conclude I'm criticizing printing thins in a book.)
And another case where it isn't feasible to write the book in a self-contained manner. In that case, the choice is between a book with urls to external resources or no book at all. OPs blanket stance against URLs in books is short-sighted because the only way it can be realized is to simply have fewer choices of books.
Probably OP should argue that books should have as few urls to external resources as possible, and the subject of those urls should be inherently dynamic and fundamental to the book, and the book should include a credible plan for maintaining the external resources for the useful lifetime of the book (which could be a long time).
Sorry, this may be too nuanced for the internet.
this logic doesn't draw any distinction between code and natural-language text; it's true that it's a somewhat restricted argument against printing things in books, because it doesn't argue against printing 'self-contained' things that 'don't need to change' in books. but it's an argument against printing natural-language text in books to exactly the same extent that it's an argument against printing code in books
ironically, it works much better as an argument against printing urls in books than as an argument against printing code in books. c or c++ or java or perl or javascript printed 25 years ago still works fine, but most urls from 2 years ago are already broken. natural-language text written about the c++ or javascript code 25 years ago is somewhat more likely to have become incorrect than the code is
python is an exception here, since it's been taken over by the sort of fashionistas who wouldn't be caught dead wearing last season's standard library, and are actively taking steps to sabotage backward compatibility
>FreeBSD is extremely robust and powers some of the largest internet sites in world including Yahoo!. FreeBSD 6 Unleashed provides complete coverage of everything you need to know to use FreeBSD to its full potential, including coverage of FreeBSD 6.0. This edition includes updated coverage of Apache, MySQL and Sendmail, as well as added coverage of PowerPC support for Macintosh G3 and G4 platforms. This is the most up to date, comprehensive reference on the market covering FreeBSD 6.0.
Everyone was using Eclipse (or us greybeards sticking to our emacs and ((neo)v)im, by then so we ALL used them as monitor stands.
[1] https://www.amazon.com/Princeton-Companion-Mathematics-Timot...
with safe settings it gets about 3 kilobytes per page; at 130 kilobytes per page read success rates are nonzero
The use of an "idiosyncratic"/external library is in itself an anti-pattern. Book closed, next book.
2. Make the first exercise in all books be to code a simple barcode image interpreter. And just include the walkthrough and source as typed text.
You should be able to get a few MB on a page easily. Future proof as long as there are cameras on phones.
A few hundred Kb, maybe, but a few MB seem unlikely. If I take the best case scenario (no optical aberration, perfect sensor...), my phone has a 48MP camera. We cannot have 48M * 3 colors as those 48MP are after Bayer matrix handling. We also cannot have more than one bit of information per pixel, due to printing often not having "real" greyscale but some kind of dithering and you don't know for sure how it would interact with your sensor. So in the best case, 6MB. But then, you need to add error correction: books prints are not perfect, especially at a sub-0.1mm scale. They are also not perfectly planar as paper is grainy. And the camera is not exactly at a 0 angle... In the 3 axis. So you would need to have the printed pixels be way larger than the sensor ones to be able to offset this. And so on.
From there, I simply listed sources of error that would make it worse and words. The only place I could see conflation occurring is when I wrote about "sub 0.1mm" which indeed refers to the printed thing, and correspond roughly to the tolerance that would be needed to achieve millions of "printable" pixels, but even if it's about the printed pixels, it still limits the amount of information that would be stored.
Would you mind indicating where there seem to be confusion according to you? Re-reading it quickly, the comment seems consistent and indicates that both the camera pixels AND the printed pixels would cause issue.
In another example, take the Machine Identification Codes (MIC) tracing dots that basic home printers can produce [2], (I bet the publishing industry could do much better to produce a high density grid.)
These dots have a stated diameter of 0.1 mm, and on an 8”x10” area one could get a grid of 80x25.4x25.4x(1/0.1mm)x(1/0.1mm)= ~5.1M dots.(wikipedia claims larger spacing, but that must be the protocol, printing itself allows for highly precise positioning) And that’s just for one color. Use CMYK (you could imagine a sub-project to design a 8bit color based dot scheme) and compression, and even with ECC losses I can see a few MB of encoded source per page being possible. And writing that decoder would be a great exercise!
[1]: https://www.docucopies.com/image-resolution/
[2]: https://en.m.wikipedia.org/wiki/Machine_Identification_Code
If your book's code does not work based on what is in the book, then selling the book is fraud.
Ah, no, programming language runtimes are Ok, no need to include them. But then if you write a book about React, or MySQL, or... well, you get the point.