The Story Behind “100 Go Mistakes and How to Avoid Them”

381 points by Kerrick 2 months ago | 130 comments
  • mtlynch 2 months ago
    >I tried to explain how review workflows work in a PR-based setup, and gave concrete suggestions for how we could improve the process. But they didn’t want to try it. That might sound like a small thing, but at that stage, all I wanted was a smooth and efficient collaboration process. The easier it was for me to track changes, the better.

    I'm surprised the copy editor was more comfortable using git than using a web-based review tool to leave comments, especially given that she was reviewing a Go book and didn't seem to know what Go was.

    How does that even happen? It seems bizarre that Manning had this copy editor at all.

    I recently had a negative experience with Manning. I sent them an email saying that I'm in the process of writing a book, and I'm self-publishing it, but I was curious about the possibility of applying to Manning for a second edition. I asked whether they accept second editions after a self-published first edition and what document formats they accept.

    I got back a form letter telling me that they'd rejected my proposal. When I followed up and said I didn't send a proposal but was asking preliminary questions, they told me that they understood I hadn't sent a proposal, but they were going off of the table of contents on my book's website. I guess they decided to pre-emptively reject me?

    They also only said Google Docs as a document format, but based on this blog post, clearly they accept AsciiDoc.

    • thi2 2 months ago
      I must compliment your ability to keep the reader hooked, I had to see what chapters they saw, stalked your website and ended up reading the whole post about your pre sale.

      This is pretty off topic but did you test how your book works on an E-Reader? I check a sample chapter and there where a lot of pictures and colors to distinguish information, this will probably not work very well on my Kindle.

      • mtlynch 2 months ago
        Oh, thanks!

        The first few chapters, I've been primarily targeting web and not testing on e-readers. I figured that until I knew whether people actually wanted to read it, I should just focus on making the web excerpts look decent and try to avoid over-optimizing for web.

        Now that the book is officially a go, the PDF version is a first-class citizen, and I'll be testing e-reader experience on my rm2.

      • Cthulhu_ 2 months ago
        That kinda blew my mind too, I'd expect the complaint to be about needing to use some online review tool. Editing the asciidoc source directly sounds archaic, and I was expecting the authoring / editing world to have had 'code review' style software years before the software development world did.

        I mean all mainstream word processing applications have a 'commentary' / 'review' mode where someone can leave comments and suggest edits.

      • Groxx 2 months ago
        Since you're in here, if I can recommend: sync.Pool with non-fixed-size objects is a source of many problems. https://wundergraph.com/blog/golang-sync-pool as a decent overview, and https://github.com/yarpc/yarpc-go/issues/2355 has been my recent plague.

        If you browse around Go's stdlib use of sync.Pool, you'll see a variety of tiered pools with fixed sizes, and many drop anything over a large enough size (sometimes gigantic! as much as 16KB!): https://cs.opensource.google/go/go/+/refs/tags/go1.24.0:src/...

        It's a pretty well-established gotcha, sadly, and https://github.com/teivah/100-go-mistakes/blob/master/src/12... falls right into it.

        • lenkite 2 months ago
          Wish Go had introduced memory arenas. Most of the use cases for pools could have been cleanly solved by arenas.
          • dilyevsky 2 months ago
            Go has had experimental arena api since 1.22 or so
            • 9rx 2 months ago
              The experiment failed, though. It is dead at this point.
              • jensneuse 2 months ago
                I think they removed arenas again.
                • 2 months ago
              • a-french-anon 2 months ago
                Maybe I'm wrong, but when reading the first article, it seems like the entire thing exists mainly (not completely) because Go's GC isn't generational.
                • Groxx 2 months ago
                  Maybe somewhat, but it's not hard to get pathologically bad GC behavior out of generational GCs either. Pools / manual memory management will always have some reasonable use cases.
              • ryanbigg 2 months ago
                On the topic of copy editing you raise: I wrote a book in DocBook for Manning in 2010. DocBook is XML, so I structured it with opening / end tags on their own line, content in the middle. As you would with a HTML document.

                After copy editing multiple chapters, they sent it back to me with all the content on a single line. I was so incredibly upset that they ditched all my painstaking format that I almost abandoned the project there + then.

                It sounds like from your experience that it has barely changed. I ended up moving to self-publishing so I have a greater control over the whole process. I wrote it up long-form here: https://ryanbigg.com/2015/08/my-self-publishing-success-stor...

                • ahtihn 2 months ago
                  Maybe I'm misunderstanding, but you're saying you formatted XML by hand?

                  Someone likely loaded that into some tool, made changes and saved and likely never even looked at the XML.

                  Why would anyone care what the XML looks like?

                  • fc417fc802 2 months ago
                    Not needing to care in the slightest is one of the major value propositions of that sort of syntax, at least IMO. If it does happen to matter for whatever reason that's what formatting tools are for.
                    • Cthulhu_ 2 months ago
                      Because in this case it was used for its combination of both human and machine readability, but the reviewers disregarded the former.

                      Might as well write it in Word if that's the case.

                  • onionisafruit 2 months ago
                    This book format lends itself very nicely to a book club. I was in one with both new and experienced gophers. The mistakes are great discussion points. The veterans got to share stories when they've made whatever mistake or how they've avoided it over the years. The noobs often made comparisons with other languages.

                    A little secret about the book is a lot of the "mistakes" are introductions to some aspect of Go worded as a mistake. "Not using fuzzing" and "Not using errgroup" are a couple of examples.

                    • relistan 2 months ago
                      O’Reilly author here. Seems the author stumbled over pitching them the book. You can almost certainly start with an email. Our initial contact with O’Reilly was only an email. We filled out a small form later with the details of the proposal, but it was not laborious. I can also attest that their tooling is great. From any git commit I can generate a full version of the book in any of its supported formats. I wrote all of my part of the book in vim.
                      • alp1n3_eth 2 months ago
                        Is there a good example repository to see how it's done?
                        • relistan 2 months ago
                          They host their own repos, and builds are done on their system, but the layout is pretty simple. Numbered, named files in asciidoc, markdown, etc. your choice.
                      • JeremyMorgan 2 months ago
                        Hello fellow Manning author! This book is fantastic. I remember reading through a lot of it a couple years back. Super helpful and it's one of those books you can pick up, grab a nugget or two of good info and come back later.

                        Now that I'm starting another big Go project I'm going to look at it again.

                        What I like most about this book is it feels like it's all "real world" stuff. You can tell the author has built a lot with Go and can save you time by telling you were the potholes are. Great stuff!

                        • Cthulhu_ 2 months ago
                          > You can tell the author has built a lot with Go

                          That was the funny part from the intro of the article - the author had not, in fact, build a lot with Go at the time.

                          But, it proves you don't actually need to in order to become knowledgeable about a subject and / or write a book.

                          • Suppafly 2 months ago
                            >the author had not, in fact, build a lot with Go at the time

                            So many programming books are like that, and usually it shows.

                        • adeon 2 months ago
                          I got a question about the example shown, the goroutine one marked as #63, I'd copypaste but it's an image.

                          Is there a reason the common mistake is about goroutines specifically? If I instead just made function closures without launching off goroutines, would they all refer to the same 'i' variable? (I assume it's maybe just that the mistake tends to go hand in hand with goroutine-launching code in a pattern like that).

                          I'd presume the book would say right after the example :)

                          But otherwise: the author gets serious respect from me for going through that process, taking feedback and learning how to communicate, i.e. taking "how do I make a good book?" very seriously and trying their best. And also things like for putting their foot down when the problematic copyeditor. I'm almost interested in the book, not for learning about Go but learning about what it looks like when I know the writing has some serious intent behind it to communicate clearly.

                          • teivah 2 months ago
                            More details here: https://100go.co/#not-being-careful-with-goroutines-and-loop.... My example was probably terrible as it's one of the three mistakes in the book that aren't relevant anymore, thanks to Go's recent updates.

                            Thank you very much for your comment, though. It means a lot.

                            • adeon 2 months ago
                              So not only do you write a full book, but you keep the content online, up to date by making sure readers are informed of new developments that might make advice irrelevant? And you are able on the spot to say "one of three mistakes that are not relevant anymore"? You impress me, random book-writing Internet person.

                              You give me a feeling you really care about the craft and just making a good useful resource, which what I respect. I looked around the site and bookmarked it as a technical writing example I might go to read around now and then.

                              I sometimes teach coding or general computing things (but hands-on, less about writing) and I've come to appreciate that sometimes it is extraordinarily difficult to educate on or communicate complicated ideas.

                              Quoting you: To give you a sense of what I mean by improving the book “over and over“, keep in mind that between feedback from my DE, external reviewers, and others, there are parts of the book that I rewrote more than ten times.

                              I also do rewriting especially with content I intend to be a resource or education piece. Obsessively rewrite. Make it shorter. Clearer. Oops that reads like crap let's start over. IMO having an urge to do this and address all feedback or your own itches means you care about your work. Just have to remind myself that that perfect is the enemy of good enough (or something like that I forgot if the expression went exactly like that).

                              • Cthulhu_ 2 months ago
                                If you'd ever write a follow-up, would you just remove "mistakes" and end up with the book "86 Go mistakes and how to avoid them", or find more?
                              • ljm 2 months ago
                                I think #633 must be a typo, or just a fumbled explanation.

                                "We might expect this code to print 123 in no particular order" should really say "exactly" or "in order", since it's proved in the next paragraph to be inconsistent.

                                And that would be the layman's explanation of concurrency resulting in things added sequentially happening out of order.

                                And assuming FIFO on async execution, akin to running everything in series, is probably the first mistake anyone will make when they encounter concurrency for the first time.

                                • amarshall 2 months ago
                                  The problem isn’t that they might be out-of-order. The problem is expecting that they merely might be out-of-order and actually getting missed and duplicated values due to the timing of shared memory access. This was enough of a problem that they [changed the behavior][1] in Go 1.22.

                                  [1]: https://go.dev/blog/loopvar-preview

                                  • adeon 2 months ago
                                    Yes, that was the crux of my question (and was answered by that link when I checked teivah-given link, which linked https://go.dev/blog/loopvar-preview right there as well). Basically I wondered if the example given was really about:

                                    1) In Go, the 'i' variable in the for loop is the same 'i' for each round of the iteration, meaning closures created inside the loop all refer to that same 'i' variable, instead of getting their own copy of it. Very easy to accidentally think the all closures have their own copy of 'i'. Goroutines are only mentioned because in Golang this mistake tends to come up with Goroutines because of a common code pattern.

                                    OR

                                    2) Goroutines themselves either behave or have some weird lexical scope rules in a way I don't know and it doesn't really have to do with closures but an entirely Golang-foreign-alien concept to me I cannot see, and this is why the book example had Goroutines mentioned with the mistake.

                                    I rarely write Go myself so I was curious :) It looks like it was 1) unless I am bad at reading, and I think the Go 1.22 change is good. I could easily imagine myself and others making that mistake even with the knowledge to be careful around this sort of code (the link shows a more complicated example when scrolling down that IMO is a good motivating example).

                                  • teivah 2 months ago
                                    #63 isn't about the lack of execution guarantees when you execute multiple goroutines without proper synchronization; it was related to loop variables and goroutines.
                                • goostavos 2 months ago
                                  This is a lovely write up. I don't have anything real to add in this comment, but somehow just clicking the upvote button doesn't feel like enough.
                                  • teivah 2 months ago
                                    I just noticed my post was on HN. Thank you very much :)
                                    • 4ndrewl 2 months ago
                                      Just came here to write exactly the same!
                                  • turtleyacht 2 months ago
                                    Per author, this book started the "100 _ Mistakes and How to Avoid Them" series. That opened a whole new avenue of books based on programming language.
                                    • re-lre-l 2 months ago
                                      > I was working in Switzerland, refactoring a C++ legacy codebase...

                                      Such a nice place to work, where you can just decide "Let's implement thing A in a completely new stack for us that shows promise" and then, after some time, say, "Ah... this is too hard, bad decision though. Let's try another one"

                                      • tmtvl 2 months ago
                                        Sensei's Library has a collection of pages about mistakes made in Go: <https://senseis.xmp.net/?Mistakes>
                                        • leeuw01 2 months ago
                                          This is about the boardgame, not the language?
                                        • m1keil 2 months ago
                                          > I learned a ton from my DE. Like, really, a ton. Before that, I had been writing on various blogs for about a decade, but writing online is all about being direct because most people don’t have time. With a book, it’s different. People made a deliberate decision to buy your book. Now, it’s your job to bring them somewhere valuable. And if that takes time (meaning more words), so be it.

                                          I have a hard time with this point. It feels to me like a lot of books have A LOT of unecassery padding all over the place.

                                          The example of taking 28 words and turning it to 120 is pretty good at showing this. The first paragraph is totally pointless - we are reading a book about 100 most common mistakes, obviously this mistake is very common, how did this increased the value?

                                          Then we have another line that explaining what happens in the code, which is totally useless because the code is super trivial.

                                          Then the code, with more explanations on the side as if the previous line was not clear.

                                          And only after that we get to the crux of the issue.

                                          I understand that book publishers feel they need to justify the price of a book by reaching the 300p mark in some or other way, but in my way this only makes the book worse.

                                          • teivah 2 months ago
                                            It's your opinion, nothing wrong with it. Let me try to see if I can make you change it at least a bit.

                                            > The first paragraph is totally pointless - we are reading a book about 100 most common mistakes, obviously this mistake is very common, how did this increased the value?

                                            There are different levels in terms of common mistakes, and this one was probably one that all the devs did at some point. So I think highlighting the fact it's a frequent one does make sense.

                                            > Then we have another line that explaining what happens in the code, which is totally useless because the code is super trivial.

                                            I have a rule: always explain the intention of the code. Even if it's 5 lines of code, it helps the reader to better understand what we will want to highlight.

                                            > Then the code, with more explanations on the side as if the previous line was not clear.

                                            The explanations on the side do not impact the size of the book so the argument doesn't hold. I did it in many code snippets to highlight where the reader needs to focus.

                                            > I understand that book publishers feel they need to justify the price of a book by reaching the 300p mark in some or other way

                                            This is more about guiding the readers, making sure the expectations are crystal clear and that they can follow me throughout an explanation. You judge it as a criteria to justify the price of the book, but it's not the real reason. At least not for my book and I'm sure it's the case for many others :)

                                            • m1keil 2 months ago
                                              > This is more about guiding the readers, making sure the expectations are crystal clear and that they can follow me throughout an explanation.

                                              Sure, but this holds true for the blog version as well, right?

                                              To be clear, I'm not advocating for The Little Schemer version, and am not arguing that the blog version is the best it can be, but surely we can agree that book padding phenomenon does exist.

                                              By the way, I have read parts of your book over at O'Reilly Learning, and I do think it is a good book. So I'm not trying to take a dump on your work. My criticism is aimed at publishers.

                                              • teivah 2 months ago
                                                No worries I didn't take it as a criticism. I understand your point. I mean when we sign a contract there's a minimum number of pages to write. But personally, I never felt the pressure of having to add more stuff.

                                                Instead, my DE multiple times told me that it's better to favor just-in-time teaching over just-in-case teaching. Meaning multiple times, he made me drop certain section because they weren't really serving the chapter. They were "perhaps helpful" and he made me drop all of those.

                                                I guess it also depends on who you're working with and which publisher. On this aspect, Manning was fair, imo.

                                            • 2 months ago
                                            • pier25 2 months ago
                                              > Adding comments in the source code itself

                                              I've worked with editorial teams and I'd rather have that than PDFs and/or Word files without version control.

                                              • methods21 2 months ago
                                                "Yet I think Tim’s single review was possibly as valuable as all the others combined".... and yet you don't even tell us anything about his review.... disappointing esp. considering the screenshots/level of details on other input.

                                                On a different note, def. feel you pain regarding the copyeditor.

                                                • teivah 2 months ago
                                                  His review contains comments annotated on a book of 300+ pages. I don't think it would have made this section any better by deep diving into his review.
                                                • meling 2 months ago
                                                  I read it about two years ago, and would definitely recommend it. It has a similar vibe to Josh Bloch’s Effective Java.
                                                  • tyho 2 months ago
                                                    The single example given here is incorrect. Since Go 1.22 loop variables have per-iteration scope, the "broken" code is deterministic and correct.

                                                    https://go.dev/blog/loopvar-preview

                                                    • teivah 2 months ago
                                                      Outdated I'd rather say :) I documented here https://100go.co/#not-being-careful-with-goroutines-and-loop... but you're right, it was fixed (alongside 2 other mistakes in the 100).
                                                      • yndoendo 2 months ago
                                                        I still need to support Windows 7 in my industry. The last supported version is 1.20. Outdated is relative.
                                                        • tyho 2 months ago
                                                          I wrote some code today and I relied on the new behaviour. I felt a little dirty.
                                                        • josefx 2 months ago
                                                          That was an issue in 2023? Quite sure C# fixed something similar back in 2012. Is Go still proudly reinventing the wheel, wooden and filled with termites?
                                                        • musicale 2 months ago
                                                          The go mistakes that tend to bother me the most are things like gc pauses, lack of first-class named and default arguments, lack of exceptions, lack of subrange types, etc.

                                                          I usually avoid them by not using go. Or waiting until missing features (generics) are added.

                                                          • teivah 2 months ago
                                                            Generics are already there.
                                                            • musicale 2 months ago
                                                              Indeed. And we only had to wait ten years for them, from Go 1.0 to 1.18.
                                                          • lexoj 2 months ago
                                                            I purchased this book on audible (because it said PDF version as well) but PDF version had only some code and not the entire book. Sorry if this is how Audible works and if its not related to this book per se. Looking forward to listen to it.
                                                            • codazoda 2 months ago
                                                              If you’re interested in publishing a book, please reach out and let me know what’s blocking you. My email address is in my profile. I’m not selling anything here, I want to understand the issues you’re facing.
                                                              • kickbribe 2 months ago
                                                                As someone interested in learning Go is this great, thank you!
                                                                • 2 months ago
                                                                  • T3uZr5Fg 2 months ago
                                                                    [dead]
                                                                    • curtisszmania 2 months ago
                                                                      [dead]
                                                                      • tsukikage 2 months ago
                                                                        [flagged]
                                                                        • onionisafruit 2 months ago
                                                                          Not that, but I did think he wrote a second book about writing the 100 mistakes book. I don’t claim that’s a reasonable reading of the title, but it’s how I read it.
                                                                        • timbit42 2 months ago
                                                                          [flagged]
                                                                          • quaunaut 2 months ago
                                                                            I'm not a big fan of Go, and I think you could write this about nearly any language.
                                                                            • onionisafruit 2 months ago
                                                                              I'd love to try a language that you couldn't write a similar book about. Any suggestions?
                                                                              • grepexdev 2 months ago
                                                                                Could you let me know what language doesn't have at least 100 common mistakes across a broad range of developers with varying skill level?
                                                                                • ninetyninenine 2 months ago
                                                                                  Did you know there exists languages that don't have run time errors? Languages that you can never crash outside of an OOM.

                                                                                  That means you can't find a language with no mistakes. But across all languages there are languages with astronomically more gotchas and mistakes then others.

                                                                                  Golang is one of these languages that is astronomical. I mean just compare it to the language with zero runtime errors.

                                                                                  • 9rx 2 months ago
                                                                                    > Did you know there exists languages that don't have run time errors?

                                                                                    Probably not. All those languages failed.

                                                                                    • Thaxll 2 months ago
                                                                                      There is no such language, even Rust has many footguns.
                                                                                      • onionisafruit 2 months ago
                                                                                        Most of the mistakes in this book and general mistakes you make when programming aren't about crashes or other runtime errors. They are about writing code that is overly complex or otherwise difficult to maintain.
                                                                                        • grepexdev 2 months ago
                                                                                          I don't think Go is particularly esoteric to where these "gotchas" are a big problem.

                                                                                          In fact, I would argue that the gotchas are an intentional part of Go's design philosophy. I think it is strange to work in Go when coming from another language because of this, which leads people to think Go sucks.

                                                                                          • ljm 2 months ago
                                                                                            This guy writes Malbolge and has zero runtime errors because he can't compile it.
                                                                                            • Yasuraka 2 months ago
                                                                                              Did you know that this book is about mistakes that humans make?
                                                                                          • JeremyMorgan 2 months ago
                                                                                            Disagree. Every language has quirks, and best practices.
                                                                                            • ziddoap 2 months ago
                                                                                              You can make 100 mistakes in literally every language.
                                                                                              • teivah 2 months ago
                                                                                                Agreed. That was also my point when I mentioned the book started the "100 ${LANGUAGE} Mistakes and How to Avoid Them" series at Manning.
                                                                                                • ninetyninenine 2 months ago
                                                                                                  There's an infinite amount of mistakes in every language. Obviously the meaning behind this is mistakes only makeable in golang.
                                                                                                • 9rx 2 months ago
                                                                                                  Why would anyone take time to write a book like that for a failed language?
                                                                                                  • wesselbindt 2 months ago
                                                                                                    Maybe because you're stuck with it because a bunch of software has already been written in it, in need of maintenance and extension. Or maybe because the browser only runs javascript.
                                                                                                    • 2 months ago
                                                                                                      • 9rx 2 months ago
                                                                                                        If a bunch of software is written in a language, that doesn't suggest failure. More like resounding success.
                                                                                                      • ninetyninenine 2 months ago
                                                                                                        Because they don't know it's failed.
                                                                                                        • 2 months ago
                                                                                                      • wesselbindt 2 months ago
                                                                                                        A lot of replies to your comment conflate possibility with necessity. Could and need are different things.
                                                                                                        • Barrin92 2 months ago
                                                                                                          It sounds like the opposite, a language popular and practical enough to the point where people actually use it across a wide range of cases and skillsets.

                                                                                                          The reason why the books don't exist for <highbrow language of choice> is because there's only 50 programs written in it, 49 of which are tooling for the language.

                                                                                                          • ninetyninenine 2 months ago
                                                                                                            Every language has mistakes. But it's also 100% true that many languages have more mistakes then others.
                                                                                                          • revskill 2 months ago
                                                                                                            A good language should leave no room for mistakes.
                                                                                                            • 9rx 2 months ago
                                                                                                              But a good language should also be useful, and you can't have something both useful and without room for mistakes. A curious contradiction.
                                                                                                              • adamors 2 months ago
                                                                                                                The best applications have no bugs, and you can only make sure of that if you don’t write any code.
                                                                                                                • stpedgwdgfhgdd 2 months ago
                                                                                                                  The language that does not have room for mistakes cannot be used by humans.
                                                                                                                  • revskill 2 months ago
                                                                                                                    We need it for llm agent.
                                                                                                                  • Cthulhu_ 2 months ago
                                                                                                                    That's just one dimension of "good" though, every language has its own pitfalls, some more than others. Go has pitfalls, sure, but the language it was designed to replace (C/C++) has more of them.

                                                                                                                    And languages with no room for mistakes have their own issues, like readability or productivity, but I don't have any experience with those; what language(s) are you thinking of? I don't know it myself but Rust seems more "bolted down" when it comes to that aspect.

                                                                                                                    • pessimizer 2 months ago
                                                                                                                      I agree. It's sad that the only languages that exist are the bad ones.
                                                                                                                    • begueradj 2 months ago
                                                                                                                      > (to be honest, I was also a significant source of inspiration!)

                                                                                                                      There is no honesty in praising yourself, no matter what you did and achieved.

                                                                                                                      Honesty is when you pay tribute to someone else by saying he is a source of inspiration.

                                                                                                                      • esrch 2 months ago
                                                                                                                        In this case the use seems appropriate since he was the source of inspiration for mistakes, so he wasn't praising himself.
                                                                                                                        • teivah 2 months ago
                                                                                                                          I said I was a source of inspiration for the mistakes in my book. Said differently, I've done a lot of mistakes myself which ended up being a section in the book.
                                                                                                                          • stpedgwdgfhgdd 2 months ago
                                                                                                                            To be honest, i doubt whether you get what he implied