oussamarouabah/awesome-go-style

A collection of Go style guides

This is a collection of style guides for Go.

Be sure to read about writing engineering guidelines before trying to adopt one of these wholesale.

(For more commentary on these, see my blog post Idiomatic Go Resources)

The Classics

• Go Style (Google Style Guides)
• Effective Go
• CodeReviewComments
• Go Proverbs

Googler Talks

• What’s in a name?
• Package Names
• When in Go, do as Gophers do
• Twelve Go Best Practices
• Style guidelines for Go packages
• Idiomatic Go

Go Wiki Pages

• Target-specific code
• Assembly Policy
• Commit Messages
• TestComments

Non-Googlers

• Go Best Practices 2016
• Go for Industrial Programming
• Practical Go: Real world advice for writing maintainable Go programs
• The Zen of Go
• godocgo: Effective Go documentation

Further Reading

• The Ideas That Shaped Go
• Software Engineering at Google

Corporate/Project-specific Style Guildes

• bahlo/go-styleguide
• CockroachDB
• Edge X Foundry
• GitLab
• Hyperledger
• Magnetico
• Sourcegraph
• Thanos
• Uber

General tips for Code Reviews:

• Vitess.io Code Reviews
• Google Engineering Practices

My own attempt at best practices for TODO comments (extracted from existing Go practices, but otherwise mostly undocumented):

// For TODOs, BUGs, and NOTEs please use the standard form:
//
//    // TODO(username): ...
//
// The username (generally yours) means "for more information see", not
// "I claim responsibility for fixing this." Please use TODO rather than FIXME,
// XXX, HACK, etc.  This limits the number of things to grep for.
//
//    * TODO denotes missing features or functionality
//    * BUG denotes known broken code; these are displayed in godoc
//    * NOTE is used to highlight a particularly important or subtle section of code
//    * SECURITY and SECBUG are used for security related notes and issues

If you have a bug tracker, TODO(bug#) is probalby more useful as they're likely to stay static while maintainers move over time. Similarly, including dates or release versions in the comment can ensure TODOs are revisisted at appropriate times.

Find this useful? Buy me a coffee!