Idiomatic Go Resources

Every time the discussion comes up around “What does good Go code look like”, the response is “check the standard library”. However, not all of the standard library is a good example. Some of it was written early on, before styles had settled down or before best practices were understood and have now been cemented due to neglect or the Go1 Compatibility Guarantee. A better place is to read the evolving Best Practices documents that give style guides that come with the experience of lots of code written, reviewed, and deployed to production, and debugged.

These articles represents only a fraction of the words that have been written about Go style, and this is by design my own opinionated list. Items which I feel don’t contradict each other (too much..) and come backed by significant experience writing high-quality Go code. Don’t feel sad if your favourite has been left out (but please let me know about it!)

The Classics

These lists are the fundamental Go guidelines. They’ve been around for ages and almost all Go projects do (or should) follow their advice.

Effective Go: The grand-parent of them all. There’s an open bug about freezing it and replacing it with something more dynamic, but until then this is absolutely Required Reading.

CodeReviewComments: The second fundamental building block of Go style guides. Probably the most linked-to. The description: “This page collects common comments made during reviews of Go code, so that a single detailed explanation can be referred to by shorthands. This is a laundry list of common mistakes, not a comprehensive style guide.” Many of these guidelines are checked by golint.

Go Proverbs: Rob Pike’s list of pithy, poetic statements. It’s a bit terse, so go watch the associated talk . The list of proverbs can be printed out and hung next to your monitor.

These first three are Primary Sources, or perhaps Word Of God for those familiar wth TVTropes. Ideas and tips from the language designers on how the language is meant to be used.

Googler Talks

This second set of resources are from Googlers sharing code style guidelines. These again come from the experience of writing, reading, and reviewing large amounts of Go code.

What’s in a name? : Andrew Gerrand talks about naming things.

Package Names: From Sameer Ajmani on the Go blog. Packages are important, and so are the names you choose for the various pieces.

When in Go, do as Gophers do : Fumitoshi Ukai talks about writing “readable” code in Go.

Twelve Go Best Practices : From Francesc Campoy. (And don’t forget to subscribe to Just For Func).

Style guidelines for Go packages : JBD’s write-up of package-level practices.

Idiomatic Go: From Dmitri “shurcooL” Shuralyov. Similar to CodeReviewComments. A short list backed with examples from the standard library. (I’m putting this under Googlers because even though he wasn’t at Google when he started this list, they were all gleaned from “official” sources.)

There are some relevant pages on the Go Wiki for more esoteric topics. These are more specific to the Go project, but provide reasonable guidance none-the-less: Target-specific code, Assembly Policy, Commit Messages, TestComments .

Non-Googlers

It feels silly to make this distinction. However, not everything that applies inside the Big G makes sense externally. It’s important to look at what the experience is for developer outside of Google’s walls.

Go Best Practices 2016: Peter Bourgon’s updated version of his talk from 2014. Lots of good info here. A voice of experience deploying production Go code in a number of environments.

Go for Industrial Programming : Another excellent article from Peter, this one focussing on writing Go code that allows for stability and clarity in the face of highly mutable business requirements of modern small software shops.

Practical Go: Real world advice for writing maintainable Go programs: From Dave Cheney, a full workshop.

The Zen of Go. More brilliant wisdom from Dave Cheney.

godocgo: Effective Go documentation: Documentation is important. Nate Finch gives a tutorial on how to make the most of godoc.

Further Reading

Many of Go’s best practices stem from the desire to solve issues encountered with large-scale software engineering. I wrote about these early influences in The Ideas That Shaped Go. You can also read about Software Engineering at Google and see how these practices fit within the larger Google development model.

Find this useful? Buy me a coffee!