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 ```go 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 ```go // Fits on one line — keep it on one line func Sum(xs []int) int // Too long — break with every par...