What version of Go are you using?
Not version-specific (documentation)
What did you do?
Reviewed the Effective Go document at https://go.dev/doc/effective_go as a learning and reference resource.
What did you expect to see?
Guidance that reflects modern Go usage and helps readers write idiomatic Go using current language features, tooling, and commonly accepted practices.
What did you see instead?
While still valuable, Effective Go largely reflects Go as it existed around its original publication. Several important areas of modern Go development are either missing or underrepresented, which can make the document less helpful for newer Go users and less aligned with how Go is written today.
Proposal
I’d like to propose updating (or supplementing) Effective Go to better reflect modern Go practices, while preserving its original spirit and value.
Each item below includes a checkbox to track completion and a placeholder for referencing a separate issue if the work is split out. Some of the subjects are covered a little, but may need emphasis. For this reason, i've added checkboxes, so that if the core Docs team don't think any work needs doing on a certain section, then the item can be ticked/ checked as completed.
1. Modern language and tooling features
2. Error handling practices
3. Standard library usage
4. Concurrency guidance
5. Structure and usability improvements
Why this matters
Effective Go is often the first idiomatic guide new Go developers encounter. Updating it to reflect current practices would:
- Reduce confusion for newcomers
- Better align expectations with modern Go codebases
- Preserve the document’s relevance without changing its core philosophy
This is just me trying to make the world a better place, if you think this is irrelevant, please close and i'll move on.
Many thanks,
Chris.
What version of Go are you using?
Not version-specific (documentation)
What did you do?
Reviewed the Effective Go document at https://go.dev/doc/effective_go as a learning and reference resource.
What did you expect to see?
Guidance that reflects modern Go usage and helps readers write idiomatic Go using current language features, tooling, and commonly accepted practices.
What did you see instead?
While still valuable, Effective Go largely reflects Go as it existed around its original publication. Several important areas of modern Go development are either missing or underrepresented, which can make the document less helpful for newer Go users and less aligned with how Go is written today.
Proposal
I’d like to propose updating (or supplementing) Effective Go to better reflect modern Go practices, while preserving its original spirit and value.
Each item below includes a checkbox to track completion and a placeholder for referencing a separate issue if the work is split out. Some of the subjects are covered a little, but may need emphasis. For this reason, i've added checkboxes, so that if the core Docs team don't think any work needs doing on a certain section, then the item can be ticked/ checked as completed.
1. Modern language and tooling features
Add guidance on generics (basic usage and common patterns)
Document expectations around Go modules and versioning
Update tooling guidance (
go fmt,go vet,go test, modern workflows)2. Error handling practices
Add guidance on error wrapping (
errors.Is,errors.As)Clarify use of sentinel errors vs typed errors
Provide guidance on logging vs returning errors
3. Standard library usage
Include practical examples using commonly used packages (
context,sync,io,strings, etc.)Highlight idiomatic standard-library patterns seen in real-world codebases
4. Concurrency guidance
Clarify when to use channels vs mutexes
Document common concurrency pitfalls and anti-patterns
5. Structure and usability improvements
Improve navigation and sectioning of the document
Add “do / don’t” or “before / after” examples
Include anti-pattern sections to clarify when idioms should not be applied
Why this matters
Effective Go is often the first idiomatic guide new Go developers encounter. Updating it to reflect current practices would:
This is just me trying to make the world a better place, if you think this is irrelevant, please close and i'll move on.
Many thanks,
Chris.