Files
beatglow/docs/agents/CodingConventions.md
T

1.5 KiB

Coding conventions

  • Use idiomatic Go, gofmt, and the surrounding package's naming and import style. Extend existing contracts instead of introducing parallel registries or layers.
  • Wrap propagated errors with useful context and %w. Use errors.Is or errors.As when callers need to recognize them.
  • Decide recovery at the caller: a disconnected MPD server can be retried, while unusable startup configuration should return an error. Explain intentional recovery; avoid silent failures and unnecessary process termination.
  • Use structured Logrus fields for component, device, connection and path context. Keep frame/sample loops quiet; log meaningful transitions and actionable failures.
  • Keep display refreshes and controller event handling responsive. Close owned connections, files and tickers; make goroutine shutdown explicit. Review channel ownership and synchronization when changing lifecycle behavior.
  • Validate protocol responses, HCL values, dimensions and PCM formats before use. Respect Linux build constraints and hardware-specific dependencies.
  • Put focused tests beside implementations. Cover parsing, malformed input, detection precedence, failures and recovery with temporary files or fake servers. Unit tests should run without physical GPIO, displays or a live MPD instance.

Adapted from Flow's coding guide, with BeatGlow-specific lifecycle, logging and hardware guidance.