Code Guide
About
This documentation codifies the current decisions for writing readable and idiomatic Go. Adherence to the Code Guide is not intended to be absolute, and these documents will never be exhaustive. Our intention is to minimize the cognitive load required for writing readable Go so that new team members can avoid common mistakes.
The Code Guide also serves to unify the style guidance given by anyone reviewing Go code at Swoop, and should capable of being understood by anyone with sufficient experience in Go.
This documentation is intend to:
- Codify settled matters of Go style
- Express a set of principles for weighing alternate styles
- Document and provide canonical examples for Go idioms
- Document the pros and cons of various style decisions
- Help minimize surprises in Go readability reviews
- Help readability mentors use consistent terminology and guidance
This documentation is not intend to:
- Be an exhaustive list of comments that can be given in a readability review
- List all of the rules everyone is expected to remember and follow at all times
- Replace good judgment in the use of language features and style
- Justify large-scale changes to get rid of style differences
Regarding style, there will always be differences of opinion from one Go programmer to another and from one team’s codebase to another. However, it is in the best interest of Swoop that our codebase be as consistent as possible. To that end, feel free to make style improvements as you see fit, but you do not need to nit-pick every violation of the Style Guide that you find.
In particular, these documents may change over time, and that is no reason to cause extra noise in existing codebases; it suffices to write new code using the latest style guide and address nearby issues over time.
Remember that none of these decisions, or the people making them, are infallible; they’re just our best attempts at the time we made them, not wisdom received on stone tablets. If someone asks why do we do X instead of Y, please try to present the engineering reasons fairly, including for Y, and avoid argument solely by appeal to authority. It’s too easy to fall into the “well that’s just not how it’s done here” trap.
Definitions
The following words, which are used throughout the Style Guide, are defined below:
-
canonical Prescriptive and enduring
Within this documentation, principles labeled as Canonical are considered a standard that all code (old and new) should follow and that is not expected to change substantially over time. They should be understood by authors and reviewers alike, and there for must meet a high bar for comprehensibility. As such, the statements of canonical principles are generally shorter and prescribe fewer elements of style than non-canonical principles, although the reasoning justifying them will generally be longer.
-
contested Discussed and updated
Within this documentation, principles labeled Contested are normative principles that someone has challenged or questioned and the discussion is ongoing. Where possible, as long as you don’t strongly oppose the normative principle, follow that until such a the discussion is resolved and the rule is transitioned to Canonical.
-
normative Established and consistent
Within this documentation, principles labeled as Normative are agreed-upon standards of style for use by author and reviewers, in order that the suggestions, terminology, and justifications are consistent. These principles may change over time, and this documentation will reflect such changes so that reviewers can remain consistent and up-to-date.
-
proposed Documented and shared
Within this documentation, principles labeled Proposed are new principles that someone has suggested and the discussion is ongoing. Where possible, as long as you don’t strongly oppose the normative principle, follow that until such a the discussion is resolved and the rule is transitioned to Normative. Once it has transitioned, it will remain Normative long enough to be tested and analysed.
-
identified Unsure and incomplete
Within this documentation, principles labeled Identified are incomplete, where the need for a rule has been identified, but nothing has been compiled to support any stance on the matter. With no rule to follow, we are free to use our own best judgement to decide how to handle these situations.
-
idiomatic Common and familiar
Within this documentation, principles labeled Idiomatic are prevalent defacto standards in Go code and have become familiar patterns that are easy to recognize. In general, an idiomatic pattern should be preferred to something unidiomatic if both serve the same purpose in context, as this is what will be the most familiar to authors and reviewers.