Go Function Design

Compatibility: Baseline Go 1.27 (see COMPATIBILITY.md). Returning iter.Seq[T] requires Go 1.23+.

Resource Routing

• references/SIGNATURES.md - Read when designing parameters or signature readability.
• references/PRINTF-STRINGER.md - Read when using fmt verbs, Stringer, GoStringer, Formatter, or Printf-style function naming.
• references/OPTIONS-VS-STRUCTS.md - Read when choosing or implementing constructor configuration: config structs, functional options, defaults, validation, and caller ergonomics.

Follow existing API conventions and preserve signatures unless changing them is in scope.

Function Grouping and Ordering

Organize functions in a file by these rules:

1. Functions sorted in rough call order
2. Functions grouped by receiver
3. Exported functions appear first, after struct/const/var definitions
4. NewXxx/newXxx constructors appear right after the type definition
5. Plain utility functions appear toward the end of the file

Function Signatures

Keep the signature on a single line when possible. When it must wrap, put all arguments on their own lines with a trailing comma:

func (r *SomeType) SomeLongFunctionName(
    foo1, foo2, foo3 string,
    foo4, foo5, foo6 int,
) {
    foo7 := bar(foo1)
}

Add /* name */ comments for ambiguous arguments, or better yet, replace naked bool parameters with custom types.

ctx context.Context is the first parameter and is never stored; go-context owns its placement and values.

Pointers to Interfaces

You almost never need a pointer to an interface. Pass interfaces as values — the underlying data can still be a pointer.

The same holds for every parameter the function reads only as *x: a string, slice, map, time.Time, or small struct travels by value, never as a pointer to save a copy. Take a pointer when the callee writes through it, when the type holds a lock (go vet copylocks reports the copy), or when the type's methods have pointer receivers — large structs among them, per RECEIVER-TYPE.md; a type whose only pointer methods are decoders, such as time.Time, still travels by value:

func greet(name string) string { ... } // not *string: only read
func drain(q *Queue) { ... }           // *Queue: Queue has pointer receivers

Printf and Stringer

Printf-style Function Names

Functions that accept a format string end in f, so the caller knows to pass one. go vet finds a wrapper that forwards its format to fmt whatever its name. A function that keeps the format instead (a recorder, a deferred logger) carries the marker the printf analyzer documents, so a plain go vet ./... checks its calls:

func Recordf(format string, args ...any) {
    if false {
        _ = fmt.Sprintf(format, args...) // enable printf checking
    }
    entries = append(entries, entry{format, args})
}

Declare format strings as const when used outside Printf calls. A message that is not a constant is not a format: from a go 1.24 directive, go vet reports fmt.Errorf(msg) as non-constant format string.

return errors.New(msg) // or fmt.Errorf("%s", msg); never fmt.Errorf(msg)
t.Fatal(msg)           // the non-f form, not t.Fatalf(msg)

Prefer %q over %s with manual quoting when formatting strings for logging or error messages — it safely escapes special characters and wraps in quotes:

return fmt.Errorf("unknown key %q", key) // produces: unknown key "foo\nbar"

Constructors and Optional Configuration

Choose the API by how callers configure it; an option count alone does not justify functional options.

Keep required inputs separate from optional settings. Apply defaults first, then caller settings, then validate the final configuration, including interdependent fields. Where the documented zero differs from the default — Timeout: 0 meaning "no timeout" while unset means 30s — the field is a pointer (*time.Duration, set with new(0 * time.Second)) or the option records that it ran; a plain field cannot tell the two apart. Do not change an existing config API merely to introduce With* helpers. Check omitted, explicit zero/nil, and repeated settings against the documented constructor contract. Resolve known mismatches in the code before presenting it; a caveat does not make a contradictory invariant hold.

When functional options fit, preserve the repository's convention. Without one, start with function-valued options for simple configuration updates; use an interface and concrete option types when callers need capabilities that justify them. Implementation and tradeoffs live in the constructor reference above.

Changing an Exported API

In a module at v1 or later, code compiled against the old API must still compile. These changes look additive and are not:

Add instead: a new function beside the old one, which the old one calls (Open stays, OpenWith(addr string, opts ...Option) is new; Query → QueryContext in database/sql); a constructor new in this release takes a config struct or ...Option from the start, so later settings are new fields or With* functions; or a new interface that callers detect with a type assertion. A change that must break callers is a new major version, /vN in the module path (STRUCTURAL.md).

Related Skills

• go-error-handling: error returns in multi-return functions.
• go-naming: function, method, and getter names.
• go-interfaces: consumer-side interface placement and compile-time assertions; option types, the Option interface included, stay here.
• go-documentation: constructors, defaults, With* functions.
• go-style-core: general formatting and line length; signature wrapping is owned here.