https://google.github.io/styleguide/go
Overview |Guide |Decisions |Best practices
The Go Style Guide and accompanying documents codify the current best approachesfor writing readable and idiomatic Go. Adherence to the Style Guide is notintended to be absolute, and these documents will never be exhaustive. Ourintention is to minimize the guesswork of writing readable Go so that newcomersto the language can avoid common mistakes. The Style Guide also serves to unifythe style guidance given by anyone reviewing Go code at Google.
| Document | Link | Primary Audience | Normative | Canonical |
|---|---|---|---|---|
| Style Guide | https://google.github.io/styleguide/go/guide | Everyone | Yes | Yes |
| Style Decisions | https://google.github.io/styleguide/go/decisions | Readability Mentors | Yes | No |
| Best Practices | https://google.github.io/styleguide/go/best-practices | Anyone interested | No | No |
TheStyle Guide outlinesthe foundation of Go style at Google. This document is definitive and isused as the basis for the recommendations in Style Decisions and BestPractices.
Style Decisions is amore verbose document that summarizes decisions on specific style points anddiscusses the reasoning behind the decisions where appropriate.
These decisions may occasionally change based on new data, new languagefeatures, new libraries, or emerging patterns, but it is not expected thatindividual Go programmers at Google should keep up-to-date with thisdocument.
Best Practicesdocuments some of the patterns that have evolved over time that solve commonproblems, read well, and are robust to code maintenance needs.
These best practices are not canonical, but Go programmers at Google areencouraged to use them where possible to keep the codebase uniform andconsistent.
These documents intend to:
These documents donot intend to:
There will always be differences from one Go programmer to another and from oneteam’s codebase to another. However, it is in the best interest of Google andAlphabet that our codebase be as consistent as possible. (Seeguide for more on consistency.) To that end, feel free tomake style improvements as you see fit, but you do not need to nit-pick everyviolation of the Style Guide that you find. In particular, these documents maychange over time, and that is no reason to cause extra churn in existingcodebases; it suffices to write new code using the latest best practices andaddress nearby issues over time.
It is important to recognize that issues of style are inherently personal andthat there are always inherent trade-offs. Much of the guidance in thesedocuments is subjective, but just like withgofmt, there is significant valuein the uniformity they provide. As such, style recommendations will not bechanged without due discourse, Go programmers at Google are encouraged to followthe style guide even where they might disagree.
The following words, which are used throughout the style documents, are definedbelow:
Canonical: Establishes prescriptive and enduring rules
Within these documents, “canonical” is used to describe something that isconsidered a standard that all code (old and new) should follow and that isnot expected to change substantially over time. Principles in the canonicaldocuments should be understood by authors and reviewers alike, so everythingincluded within a canonical document must meet a high bar. As such,canonical documents are generally shorter and prescribe fewer elements ofstyle than non-canonical documents.
https://google.github.io/styleguide/go#canonical
Normative: Intended to establish consistency
Within these documents, “normative” is used to describe something that is anagreed-upon element of style for use by Go code reviewers, in order that thesuggestions, terminology, and justifications are consistent. These elementsmay change over time, and these documents will reflect such changes so thatreviewers can remain consistent and up-to-date. Authors of Go code are notexpected to be familiar with the normative documents, but the documents willfrequently be used as a reference by reviewers in readability reviews.
https://google.github.io/styleguide/go#normative
Idiomatic: Common and familiar
Within these documents, “idiomatic” is used to refer to something that isprevalent in Go code and has become a familiar pattern that is easy torecognize. In general, an idiomatic pattern should be preferred to somethingunidiomatic if both serve the same purpose in context, as this is what willbe the most familiar to readers.
https://google.github.io/styleguide/go#idiomatic
This guide assumes the reader is familiar withEffective Go, as it provides acommon baseline for Go code across the entire Go community.
Below are some additional resources for those looking to self-educate about Gostyle and for reviewers looking to provide further linkable context in theirreviews. Participants in the Go readability process are not expected to befamiliar with these resources, but they may arise as context in readabilityreviews.
External References
Relevant Testing-on-the-Toilet articles
Additional External Writings