Comments

There 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.

This comment has been minimized.

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/?

This comment has been minimized.

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).

This comment has been minimized.

This comment has been minimized.

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.)

This comment has been minimized.

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.

This comment has been minimized.

@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.

This comment has been minimized.

This comment has been minimized.

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.

This comment has been minimized.

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.

And explain that it does this. A minor change probably worth mentioning,
although (#28782) I'd still like to freeze this document against any substantial
changes.
Fix#30568.
Change-Id: I74c56744871cfaf00dc52a9b480ca61d3ed19a6b
Reviewed-on: https://go-review.googlesource.com/c/go/+/165597
Reviewed-by: Brad Fitzpatrick <bradfitz@golang.org>