Programming book authors: put all the code in the book
logicgrimoire.wordpress.com
logicgrimoire.wordpress.com
>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...
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
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.
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.
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
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.
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.
If your book's code does not work based on what is in the book, then selling the book is fraud.
An anachronism from before the current era, when you can take a picture of text with your phone and tell ChatGPT "transcribe this".
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.