mxaccessgw/docs/style-guides/GoStyleGuide.md

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.