Idioms and API Design

Go gives three choices: embed the type anonymously so its methods are promoted onto yours, hold it in a named field and forward only the calls you want, or depend on an interface it already satisfies.

In Go a failure is an ordinary return value of the predeclared error interface type. os.Open hands back a file and an error together, so the caller checks it on the spot and every failure path stays visible.

Nothing useful, unless the documentation says otherwise. By convention the other results are their zero values on failure, so a returned pointer is nil. Using one before returning is the classic nil dereference panic in Go code.

A type parameter constrained by any permits no operations — not even ==. With T appearing in only one position it links nothing to nothing, so the generic form does exactly what the plain any parameter does, with more syntax.

Go performs no implicit numeric conversion: mixing an int with an int64, or an int with a time.Duration, is a compile error until you write the conversion. But the conversion you wrote can still truncate or lose precision silently.

Go's convention is MixedCaps: each following word is capitalised and underscores are dropped. Case is already meaningful, since the first letter decides package visibility, so it doubles as the word separator. Underscores belong to file names.

Go's documentation tools lift the comment away from the declaration and show it on its own, so the sentence has to name its own subject. Starting with the identifier also makes the first sentence a self-contained one-line summary in package listings.

Idiomatic Go handles the failure inside the if and returns, leaving the success path unindented below it. Because Go checks an error after nearly every call, putting each success in an else pushes the real work rightward.

Every reference outside the package already carries the package name, so http.HTTPClient says HTTP twice at the call site. Go names a type for how it reads after the qualifier, so inside package http the type is simply Client.

Go keeps an initialism in one uniform case, all upper or all lower, never title case: ServeHTTP, URL, userID. In an unexported name a leading initialism goes fully lowercase, as in xmlHTTPClient.

New takes the Config by value, replaces each field still at its zero value with a named package default, and builds the object from that copy. The caller's struct is untouched, and every caller gets identical defaults.

Because callers pass only the settings they care about. Option is a function type such as func(*Client); each With... helper returns one, and New starts from a struct holding the package defaults and applies the options to it.

A type has a useful zero value when var x T is ready to use with no constructor call. bytes.Buffer, sync.Mutex and http.Client all work this way, so callers can declare or embed them and start calling methods immediately.

Make the field a pointer, such as *int or *time.Duration. A nil pointer means the caller said nothing, so the constructor's default applies; a non-nil pointer to zero means they really asked for zero.

Put both on the Config itself: a withDefaults method returning a filled copy, and a validate method returning an error. Every constructor calls them in that order, once, so validation judges the values that will actually be used.

A caller can always add concurrency to a blocking function by starting it with go, but cannot remove concurrency the package started. Staying synchronous leaves the goroutine's lifetime, its errors and how many run in the caller's hands.

Case decides it. An identifier whose name begins with an upper-case letter is exported and visible to packages that import it; a lower-case one is package-private. Importing packages cannot read, set, or even name an unexported struct field.

A context.Context parameter goes first and is named ctx; the error result goes last. Everything else sits between them, with any variadic parameter at the end, because that is the shape the standard library and every reviewer expect.

Through its constructor's parameters. main creates each collaborator first and passes them to a function such as NewThumbnailer, which stores them in unexported struct fields, so the type never reaches outside itself for a dependency.

An exported Go interface is satisfied implicitly, so any type with the right method set implements it. Adding a method enlarges that set, and every outside implementer stops compiling. A method on a struct affects only that type.

Go checks interface satisfaction implicitly, so whoever needs the abstraction can declare it later. An interface written beside its only implementation adds indirection now, hides the concrete type's other methods and fields, and buys nothing.

Go's compiler rejects unused variables and unused imports, but not unused return values. A call like f.Close() is a complete statement on its own, so nothing forces you to look at the error it returns.

It runs at package initialization, before main, so nothing can supply or check the value: the package cannot report a missing setting as an error, and a test can only change it by writing to a global.

A deferred call's return value is thrown away, so defer f.Close() discards the error reporting a failed write. Closing the file also does not flush a bufio.Writer above it, so buffered bytes are never written and the run still reports success.

An any parameter gives up the compile-time contract. The signature no longer says what is accepted, so the rule lives in a doc comment and a runtime type switch, and a caller's wrong type fails in production.