Joseph Doherty
69 lines
2.4 KiB
Markdown
69 lines
2.4 KiB
Markdown
# 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.
|