7 ms·
Programming book authors: put all the code in the book
- blueflow 3y agoI 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.
- deleted 3y ago[deleted]
- michaelcampbell 3y agoWas it just me, or did anyone else read the "TL;DR" explaining how to AVOID the antipattern to BE the antipattern?
- johnday 3y agoNo? It's in the imperative voice, it wouldn't make sense to read "do this" as a description of an antipattern.
- michaelcampbell 3y agoWhy 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?
- johnday 3y agoDescribing 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?
- lupire 3y agoThis is linguistic problem with using negative statements. Accentuate the positive. Eliminate the negative.
- joshka 3y agopfft - https://www.w3.org/Provider/Style/URI.html https://www.w3.org/Provider/Style/URI.html
- andyjohnson0 3y agoI'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
- jasperry 3y agoI 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.
- oytis 3y agoJust 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.
- InfiniteRand 3y agoIs it feasible to attach a usb drive to a book these days?
- deleted 3y ago[deleted]
- bdw5204 3y agoA 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.
- hoherd 3y agoA book with a usb port on it to download data contained within the book would be so cyberpunk. 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.billboard.com/biz/articles/news/tv-film/7775028/doritos-marvel-partner-for-guardians-of-the-galaxy-vol-2-promotion?utm_source=twitter https://web.archive.org/web/20190516225905/https://www.billb...
- cyberpunk 3y agoIt's taking me forever to upgrade all my dead tree books to usb-c, to be fair.
- Zobat 3y agoCan 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.
- Noumenon72 3y ago"printed in the book itself, so the reader can type it in" An anachronism from before the current era, when you can take a picture of text with your phone and tell ChatGPT "transcribe this".
- kunley 3y agoI think the point is to get certain understanding while typing. It is about being in the learning process, not just about retrieving the code.
- pjc50 3y agoDoes that actually work? My experience with various photo OCR tools was not working except under optimal conditions.
- Noumenon72 3y agoI have tried it on just one book and a few screenshots. I tried it on your comment just now and it timed out. Sorry!
- pjc50 3y agoThe antipattern here is the physical book, surely?
- Ensorceled 3y agoWhy? Literally everything in this article would apply to online books as well, except "type it in" would be "copy and paste"
- hyperpape 3y agoWith 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.
- falcor84 3y agoHow 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?
- deleted 3y ago[deleted]
- okonomiyaki3000 3y agoI 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?
- HankB99 3y agoTwo 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 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.
- crabbone 3y ago> 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.
- Aurornis 3y ago> 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.
- jmull 3y agoBugs emerge. Tools change. 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.)
- lewispollard 3y agoPrint code in the book, and have a URL you can check for errata. That's how it always used to be done, anyway.
- jmull 3y agoFine 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")
- kragen 3y agothis is a fully general criticism of printing anything in a book; it's not an argument against printing code in books, but against books themselves
- jmull 3y agoI 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). Sorry, this may be too nuanced for the internet.
- dustingetz 3y ago"Authors should write better and have more money"
- ralphc 3y agoBring back the 90's antipattern of making the book so thick you use it as a monitor stand.
- abhgh 3y agoI 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. [1] https://www.amazon.com/Princeton-Companion-Mathematics-Timothy-Gowers/dp/0691118809/ https://www.amazon.com/Princeton-Companion-Mathematics-Timot...
- brianmcc 3y ago"Teach yourself J2EE in 21 days, 2nd edition" remains marvellous for this :-D
- unethical_ban 3y agoMine (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.
- tmtvl 3y agoMy 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).
- cafard 3y agoInside 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.
- tokai 3y agoMaybe QR codes, containing the code in plain text, in an appendix? That would ensure easy access to the code on devices outside of the printed book.
- kragen 3y agoyou will probably want to use https://github.com/za3k/qr-backup https://github.com/za3k/qr-backup with safe settings it gets about 3 kilobytes per page; at 130 kilobytes per page read success rates are nonzero
- fransje26 3y ago> download the author’s idiosyncratic library code The use of an "idiosyncratic"/external library is in itself an anti-pattern. Book closed, next book.
- nearbygoogler 3y ago1. Print the source code in a micro-barcode in a physical appendix. 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.
- ivegotnoaccount 3y ago> 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.
- remram 3y agoI think you confused printed pixels with camera pixels along the way.
- ivegotnoaccount 3y agoI 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.
- jll29 3y agoOne 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..).
- RecycledEle 3y agoI agree with the author. If your book's code does not work based on what is in the book, then selling the book is fraud.
- l0b0 3y agoDone & done. This was one of my own bugbears. Thankfully Bash does not have a lot of boilerplate.
- chrsw 3y agoI thought programming book publishers didn't like putting complete source listings in printed material because of cost reasons.
- grodriguez100 3y agoSo 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.