# Go Style Guide

This guide defines Go conventions for the MXAccess Gateway Go client module,
test CLI, and tests.

## Baseline

- Use idiomatic Go and keep package APIs small.
- Run `gofmt` on every changed Go file.
- Run `go vet` for non-trivial changes when the module is available.
- Keep generated protobuf code under `internal/generated` unless the public API
  intentionally exposes it.

## Source Documentation

- Maintain the existing documentation style in the file, package, and
  surrounding component.
- Write comments that include business-specific or domain-specific context when
  that context is available from the code, surrounding docs, or naming.
- Document exported names when they are part of the public client API.
- Avoid comments that restate syntax or control flow.

## Packages

- Use short, lowercase package names without underscores.
- Keep the reusable library separate from CLI code.
- Keep generated code separate from handwritten wrappers.
- Prefer internal packages for implementation details that callers should not
  import.

## Naming

- Use exported names only for public API.
- Use initialisms consistently: `APIKey`, `TLS`, `HTTP`, `ID`.
- Keep MXAccess terms explicit: `ServerHandle`, `ItemHandle`, `MxStatusProxy`,
  and `HResult`.
- Avoid generic helper names such as `Do` or `Process` for command-specific
  MXAccess behavior.

## Context And Cancellation

- Accept `context.Context` as the first parameter for operations that can block.
- Do not store contexts in structs.
- Respect context cancellation, but document that canceling a client call does
  not abort an in-flight worker COM call.
- Close streams and connections deterministically.

## Errors

- Return errors instead of panicking.
- Wrap errors with useful context using `%w`.
- Support `errors.Is` and `errors.As` for typed gateway, command, and MXAccess
  errors.
- Preserve raw command replies on command errors when available.
- Redact API keys and credential-bearing values in error messages.

## Concurrency

- Avoid unbounded goroutines and unbounded channels.
- Close channels exactly once from the sending side.
- Propagate stream errors through explicit result types such as `EventResult`.
- Use the race detector for concurrency-heavy changes when practical.

## Tests

- Use table-driven tests for conversion and error mapping.
- Use `bufconn` or fake generated clients for unit tests.
- Keep integration tests behind `MXGATEWAY_INTEGRATION=1` or build tags.