GeezerVison is showing github.com — doc: freeze "Effective Go" · Issue #28782 · golang/go
doc: freeze "Effective Go" #28782DescriptionThere have been a number of suggestions to change the code inside Effective Go lately. For instance, the comments in #28773 suggest adding an example that uses strings.Builder. But in fact there are almost no mentions of library functions in the document, so starting with strings.Builder doesn't make much sense.
I may be totally alone here, but I think of the current document called "Effective Go" (EG) as a bit of a time capsule, a published book if you will.
I think it should be pretty much left alone. The continuing churn of advice and recommendations and cargo culting should not be developed there. I think even though it is old it does a fine job of saying how to write effective Go code. How to write modern, trendy, stylistic, library-aware code is different question.
I think there should be a new document that talks about the libraries (almost totally absent from EG), style (nearly ditto), "best practices" such as the thing about returning concrete types, not interfaces (which requires so many caveats I fail to understand why it's a rule), etc. I fear that if you try to incorporate that into EG several things will happen: It will become much longer; it will be changing constantly; many people will add to it; and it will lose the writing style it has, which is almost entirely mine, and therefore in my voice.
Let's freeze it and start something new and more dynamic and more current. Reacted by cznic, qaisjp, Dmitri Shuralyov, deanveloper, Sebastien Binet, U Cirello, Damien Neil, Steven E. Harris, as, Davor Kapša and 119 more Reacted by Ahmed W., Simon Law, Aynur Zulkarnaev, Felipe S. S. Schneider, Wilk, Dean Ellis, Dharampal H S, Song, Alvin McNair and uanhi Reacted by Jairo Lozano, Rinat and Anton Dolganin Reacted by Jairo Lozano and Richard Nabaasa Reacted by Oleg Kovalov, Vitaly Zdanevich, Ahmed W., Bash, Felipe S. S. Schneider, Nacim Goura, Kiarash Azarnia, KYLE SIN LYNN, moremorefaito, Felipe Blassioli and 2 more Reacted by Lars Seipel, shashank prakash, Pratik Gaur, Eduardo Piorini, sabsubsib, Kenneth Betancourt, Jairo Lozano, Ivan Sabo, Tunc Tugcu, Alexander Klakovskiy and 9 more Reacted by Felipe S. S. Schneider, kangyunjie, Azat Imaev and masamallow Activityrobpike commented on Nov 13, 2018 ContributorAuthor More actions See #27818 and #28773 for examples of where things could go if we decided Effective Go was to reflect the state of the art, a moving target. rsc commented on Nov 13, 2018 I agree about the #28773 comments being out of place. That's not what the doc is about. It's OK to avoid worrying about things like that, and the doc will become unwieldy if it must be concerned with everything at all times.
I'm all for freezing it.
I'm less sure about starting something new and more dynamic and current. That sounds great, of course, but what form would it take? How would it be structured? Reviewed? What would it contribute beyond existing materials, like say https://gobyexample.com/? robpike commented on Nov 13, 2018 ContributorAuthor More actions It might be valuable to have a separate overall guide to the standard library. There's a lot of it now, a lot more than when EG was written. rsc commented on Nov 13, 2018 Agreed. That said, what you're describing still sounds to me like Go By Example. Maybe we should focus effort there, to the extent effort is needed. benhoyt commented on Nov 13, 2018 I agree with that Effective Go should not be "How to write modern, trendy, stylistic, library-aware code". But I think it's a bit of a stretch to say my suggestion of "not modifying the receiver in String()" falls into this category -- that does seem like ineffective Go and the kind of thing that will bite someone later. (For example: "Why on earth is this Printf call modifying my sequence?!")
That said, I'd be happy for this to be frozen "like a book", however, in that case I think it should look more like a book or be packaged up somewhere else. The stuff on golang.org/doc has a very "up-to-date documentation" feel to it in my opinion (as I think it should). robpike commented on Nov 13, 2018 ContributorAuthor More actions @benhoyt As I said in the other issue, I would be willing to fix up the example (to avoid overwriting the receiver, at least), but not to the extent of using strings.Builder.
If the document is frozen, it will need an introductory paragraph saying so as well as links to further reading. Reacted by Ingo Oeser, radiant-kal, Risyandi and Burhan Ali benhoyt commented on Nov 13, 2018 Yep, sounds reasonable, thanks. josharian commented on Nov 13, 2018 Effective Go is widely linked to, has good SEO, etc. I think it’d be a pedagogical waste to consign it to be a frozen historical document. (I don’t have opinions at the moment about the specific changes being proposed.) Reacted by Matt Layher, Bryan C. Mills, Ahmed W., Liam Breck, Martin Kiesel, Oleg Kovalov, Akhil Indurti, Vitaly Zdanevich, Marcel Lanz, Mark Pulford and 17 more Reacted by Oleg Kovalov, Ingo Oeser, Aditya Maheshwari and Thirshe Perera mvdan commented on Nov 14, 2018 I mostly agree with how the scope of Effective Go shouldn't be made bigger - the page itself is already quite large, and it serves as a good basis that pretty much every Go developer should have read once.
@josharian what if Effective Go linked to other documents touching more specific topics? For example, we could have an "effective use of std" document, linking to it at the top of the page. I think that would still let us take advantage of existing links and SEO.
I think these documents already follow a certain path anyway; see the quote below. It would only be a matter of adding "further reading" links.
This document gives tips for writing clear, idiomatic Go code. It augments the language specification, the Tour of Go, and How to Write Go Code, all of which you should read first.
Reacted by Diógenes Fernandes robpike commented on Nov 14, 2018 ContributorAuthor More actions @josharian I'm not asking to delete it, just freeze it. It covers a small fraction of what people now consider best practices for writing Go code in the modern ecosystem. It focuses almost exclusively on the language itself, and in particular the language as it first appeared. I wrote it in a frenzied weekend a few days before the language was open sourced, and it's changed little since then.
I'd like to acknowledge that it hasn't aged well and supplement it rather than rewrite it. Reacted by Daniel and Jeremy Harisch networkimprov commented on Nov 14, 2018 How does "freeze" differ from "deprecate"? Reacted by NikitaMPair and Dmitry Oksenchuk Reacted by Gwyneth Llewelyn seebs commented on Nov 14, 2018 I don't think it would benefit it much to significantly change its scope, but I do think the examples in it should be good. Changes should probably be fairly rare -- in most cases, there's not much language change happening to merit them. But for instance, if Effective Go predated append(), it would be ridiculous not to update it to show current best practice. I doubt there will be many changes like this in the language's future, but if there are some, it'd be nice to have the canonical source be correct.
But it does make sense to distinguish between "new things that could possibly merit new sections or new documents" and "cases where the code or descriptions in Effective Go are probably wrong by current understanding". A preference for new documents rather than new material makes sense, but if we found actual bugs in the code, I'd think it'd be better to fix them. josharian commented on Nov 14, 2018
I'd like to acknowledge that it hasn't aged well and supplement it rather than rewrite it.
Perhaps my take is dated, but it isn't obvious to me that it hasn't aged well. From what I see, what folks are asking for tweaks and gentle evolution, not a rewrite. Supplementing it seems good. Adding prominent links to additional docs seems good. I just don't see the value in freezing it.
I can see the appeal of not having to litigate every request to change it. And I understand the relief of never having to look again at words written many years ago. I just don't think that freezing it rather than fixing little things (like sorting in a String method) would serve the Go community well, particularly as it goes through a period of rapid growth, during which time the education of new gophers is among the greatest challenges. Reacted by Liam Breck, Ben Hoyt, Oleg Kovalov, Davor Kapša, Dmitri Shuralyov, Ingo Oeser, Marcel Lanz, Chris Hines, Ilia Choly, Lucas Grigolon Varela and 9 more petar-dambovaliev commented on Jan 18, 2019
How does "freeze" differ from "deprecate"?
It defers because it is still valid.
@robpike has argued that certain kinds of additions do not logically belong there
and proposes to create something new that will supplement Effective Go. Reacted by Dmitri Shuralyov Reacted by Gwyneth Llewelyn marcellanz commented on Mar 29, 2020
I'd like to acknowledge that it hasn't aged well and supplement it rather than rewrite it.
Perhaps my take is dated, but it isn't obvious to me that it hasn't aged well.
I just don't think that freezing it rather than fixing little things (like sorting in a String method) would serve the Go community well, particularly as it goes through a period of rapid growth, during which time the education of new gophers is among the greatest challenges.
I'm here because I was looking for a specific issue I have and wanted to read about in Effective Go. Having it so prominently placed at the golang.org website implies a relevance, but reading here its a mostly years old document not reflecting current thinking of effective usage of Go, makes me feel a bit sad on the part where I then should look for such a document when not from the projects main documentation page.
I understand that it might be too much to get a revised edition out, but then better off remove it, or clearly mention its disconnected state related to the real world of Go.
Like @josharian said, I too can't distinguish which parts are outdated and which are not. It might be not even easy for someone who is in the loop of things, but how would new Gophers even get that message then? Reacted by Joe Cotton, conor, Erdem, Tsetsi Lazarov, Steven Pitts, Andrei Boar, dipushrestha, jub0bs, Anatoly Danilov, Ignacio Paricio and 3 more OneOfOne commented on Apr 13, 2021 Please don't freeze Effective Go, it was my main intro to Go, and it should be kept up to date, a lot of people prefer reading something like that rather than books and random youtube videos. Reacted by Marcel Lanz, Ingo Oeser, Zeke Lu, Alexander Babai, Lucas Grigolon Varela, Simon Law, Pierre Durand, Mark Pulford, Lewis Llobera, kayoch1n and 59 more Reacted by Marcel Lanz, Alexander Babai, Lucas Grigolon Varela, Rich, Putra Krishna, Daniel Millier, Otávio Guerra, shashank prakash, Minh Vu, Nicholas Biantoro and 14 more sfllaw commented on Nov 1, 2021 If this does get frozen, it seems like Go Code Review Comments ought to be more self-contained, especially when it refers to obsolete parts of Effective Go. Reacted by Mahmudur Rahman gopherbot commented on Jan 30, 2022 shashank404error commented on Apr 19, 2022 Been a go programmer for the last 2 years and the effective_go has helped a lot. The doc definitely went very lengthy and was not capable of exhibiting the depth of go language. Considering the go ecosystem and its effect on today's tech fabric, a new more structured doc is the demand of the hour. joecotton-wk commented on Jun 29, 2022 Looking at EG and just noticed the preamble added back in January 2022. It says that "there are no plans to update it", which leaves me with some questions:
- Does this mean EG has been frozen? I'm assuming yes, even though this issue is still open and there doesn't seem to be any consensus around it.
- If EG has been frozen, where should someone look to find relevant documentation on how to write modern, effective go? The community needs an alternative, and to my knowledge nothing else exists.
Reacted by Wilk, MagnusVortex, Travis Cashion, Egor Ivkov, Tommy Becker, Mike Wink, FelixYui, Erdem, xue, Burhan Ali and 13 more e-ivkov commented on Jul 3, 2022 @joecotton-wk A Tour of Go I believe is already more up to date than Effective Go and it also suggests a few books about advanced concurrency in the end danielzbc commented on Jul 4, 2022 For beginners of the Go, the Effect Go documentation is very helpful, allowing me to better intuitively understand the features of the Go . It is a very good learning material, but it is a pity that the update has been not undate. Reacted by Mike Wink, Siva Kommuri and SomeBottle lzap commented on Sep 2, 2022 As a big fan of Rob's written and spoken style1, I do appreciate the proposal. I wish there could be footnotes implemented in some non-intrusive way so that readers could enable or disable them to switch between the original reading experience and more updated one. EG could serve also as a hub with links to other resources, when explicitly enabled.
We have just updated our project to 1.18 today. Exciting times, yet my old 1.0 code compiles just fine. I think EG is a proof of the great design and execution. Cheers!
Footnotes
-
I've seen all Rob's talks, some of them three times or more. I am bit starved for last couple of years, there are not many new public recordings, I am crossing my fingers for new content. ;-) ↩
Reacted by Wilk, Siva Kommuri, RRadziejewski, Daniel182020, Joao Marcos, Suman Chapai, dipushrestha, jub0bs and Ivan Stasiuk sumanchapai commented on Sep 16, 2023 I think it would be beneficial to annotate the document in places where @robpike feels the need. if the original author does it, the document won't lose voice. and this annotated EG should be available under different URL leaving the original unchanged. seankhliao commented on May 9, 2025 There's already a note at the top of the document starting with "Note added January, 2022: This document was written for Go's release in 2009, and has not been updated significantly since"
Is there much more we should do for this issue?
What if we move effective go to a back dated blog post?
We can keep a redirect.
Blog posts are much more generally understood to be frozen in time vs something under /doc/. Reacted by Simon Law, Vilen Topchii, Oleg Kovalov, Michal Bohuslávek, HMage, Ayush Sharma, Dmitri Shuralyov, Gwyneth Llewelyn, Prasanna Krishna, Elmer Almeida and 15 more
MetadataMetadataDevelopmentNo branches or pull requestsIssue actions
|