styleguide

A quest for defining what it means to name things well.

Suppose one day you receive a bug report about your code (func Encode) and want to build a test to verify the fix or recreate the problem. You might have defined your code’s tests in a table-driven format, similar to below: 1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23 24 25 26 27 28 29 30 import ( "testing" "github.com/google/go-cmp/cmp" ) func TestEncode(t *testing.T) { for _, test := range []struct { name string input string output string err error }{ // 33 { ... } rows omitted } { t.Run(test.name, func(t *testing.T) { output, err := Encode(test.input) if got, want := output, test.output; got != want { t.Errorf("Encode(%q) output = %q, want %q", test.input, got, want) } // Assume I own the error contract: // // https://matttproud.com/blog/posts/go-errors-and-api-contracts.html if diff := cmp.Diff(test.err, err); diff != "" { t.Errorf("Encode(%q) err = %q, want %q diff (-want,+got):\n%v", test.err, err, diff) } }) } } To fix this, you realize you need to add another row to the table test definition, bringing the total number of rows to 34. Now suppose you add that 34th row to the test, run the test, but the code or the test doesn’t work the way you expect.

Organizing source code is a critical skill in software mastery, and this remains true in Go. Unfortunately the skill of idiomatic organization in one language does not necessarily translate to another. What makes this trickier is that code organization happens at several levels: the build system the packaging system in code in the file system To understand why, consider this Unified Modeling Language (UML) diagram of these levels and their relationships when using Go:

I would like to propose a set of neologisms for the Go Programming Language based on emergent language use: context awareness: noun, the state of an API being cognizant of and respecting the semantics of the context API. Example: Function f has context awareness. context-aware or1 context aware: phrasal adjective, whether an API has context awareness. Examples: The API consumes a context-aware function value like function f. Function f is context aware.

I’d like to share a design pattern with Go that I really find particularly elegant. It orients itself around hermetic, testable configuration using command line flags. But before I do, I need to put three questions to you since they determine if you need to do some pre-reading in advance. If you are familiar with package flag, are you aware of the Var-suffixed flag creation API variants (e.g., flag.BoolVar to complement flag.Bool)? 1 2 3 4 5 6 7 8 9 10 11 12 13 14 // https://cs.opensource.google/go/go/+/refs/tags/go1.24.2:src/flag/flag.go package flag // Bool defines a bool flag with specified name, default value, and usage string. // The return value is the address of a bool variable that stores the value of the flag. func Bool(name string, value bool, usage string) *bool { return CommandLine.Bool(name, value, usage) } // BoolVar defines a bool flag with specified name, default value, and usage string. // The argument p points to a bool variable in which to store the value of the flag. func BoolVar(p *bool, name string, value bool, usage string) { CommandLine.Var(newBoolValue(value, p), name, usage) } If you are aware of the Var variants, do you why these variants even exist?

The context API is a critical foundation for modern Go development. This is especially the case with APIs that use concurrency under the hood or perform distributed operations. Given this, I would like to do a deep dive on several topics around the context API. I expect this post to be the first of several. In this one, I cover contexts and program scopes. Program scope and contexts sound like a mundane topic, but a fair bit of confusion arises with contexts in industry. The most recent example I saw was this post on Reddit: Should contexts be used for long-running operations?