go-functions

Go Function Design

A function's surface is read more often than its body. Optimize for the reader: predictable ordering in the file, signatures that scan, no hidden bool flags.

Core Rules

1. Order by use, not alphabet. Types → constructors → exported methods → unexported → utilities.
2. Keep signatures on one line when reasonable. When wrapping, every parameter on its own line with a trailing comma.
3. Never pass *Interface. Pass the interface value; the underlying data can already be a pointer.
4. Replace naked bool/int parameters with named types or add /* name */ comments at call sites.
5. Printf-style functions end in f so go vet can check the format.
6. Prefer %q over %s plus manual quoting when formatting strings for errors and logs.

File Ordering

type Server struct{ ... }

func NewServer(...) *Server { ... }     // constructor next to type

func (s *Server) Start(ctx context.Context) error { ... } // exported
func (s *Server) Stop() error           { ... }

func (s *Server) acceptLoop() { ... }   // unexported

func parseAddr(s string) (string, error) { ... } // file-local helper

Rules:

1. Types and their constructors sit together at the top.
2. Exported methods come before unexported ones.
3. File-local helpers go at the bottom.
4. Within a section, follow rough call order.

Signature Formatting

// Fits on one line — keep it on one line
func Sum(xs []int) int

// Too long — break with every param on its own line
func (r *Repo) SaveTransaction(
    ctx context.Context,
    userID string,
    tx Transaction,
    opts ...SaveOption,
) (string, error) {
    ...
}

The trailing comma is required and gofmt-stable.

Avoid Naked Bool/Int Parameters

// Bad — what does `true` mean?
NewServer(":8080", true, 30, false)

// Better — call-site comments
NewServer(":8080", true /* tls */, 30 /* maxConn */, false /* readonly */)

// Best — named types or options
NewServer(":8080", WithTLS(), WithMaxConn(30))