go-functions

Go Function Design

Resource Routing

• references/SIGNATURES.md - Read when designing parameters, return values, named results, or signature readability.
• references/PRINTF-STRINGER.md - Read when using fmt verbs, Stringer, GoStringer, Formatter, or Printf-style function naming.

When this skill does NOT apply: For functional options constructors (WithTimeout, WithLogger), see go-functional-options. For error return conventions, see go-error-handling. For naming functions and methods, see go-naming.

---

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

type something struct{ ... }

func newSomething() *something { return &something{} }

func (s *something) Cost() int { return calcCost(s.weights) }

func (s *something) Stop() { ... }

func calcCost(n []int) int { ... }

---

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.

---

Pointers to Interfaces

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

// Bad: pointer to interface
func process(r *io.Reader) { ... }

// Good: pass the interface value
func process(r io.Reader) { ... }

---

Printf and Stringer

Printf-style Function Names