Go patterns

Basic rules

• •Follow the Effective Go guidelines for writing idiomatic Go code.
• •Use gofmt to format your code consistently.
• •Organize code into packages, each with a clear purpose.
• •Use interfaces to define behavior and promote decoupling.
• •Handle errors explicitly and avoid using panic for regular error handling.
• •Write tests using the testing package and aim for high test coverage.
• •For simple projects favour a simple structure that mirrors opensource projects, if the project grows or has complexity and lots of business logic consider using a more suitable pattern such as hexagonal (ports and adaptors) architecture
• •Avoid complexity, keep functions small and focused on a single task.
• •Avoid implementing patterns from other languages that don't fit well with Go's design philosophy, such as factory patterns or heavy use of inheritance.
• •Use goroutines and channels for concurrency, but be mindful of potential pitfalls like race conditions.
• •Document your code using Go's documentation conventions, including comments for exported functions and types, but dont explain the obvious and over document.
• •Use go modules for dependency management.
• •Regularly review and refactor code to improve readability and maintainability.
• •Leverage the standard library as much as possible before reaching for third-party packages.
• •Tag tests with build tags to separate unit, integration, and end-to-end tests where appropriate.
• •When writing integration tests, use test containers or mocks to isolate external dependencies.
• •when writing e2e tests, ensure they run against a real service, no mocks, by specifying a real endpoint.
• •Ensure there is CI/CD that:
  • •Runs tests, linters and static analysis (golangci-lint) on every commit.
  • •Builds and validates the project (binaries, libraries, or containers as appropriate).
  • •For containerized applications: publishes to a container registry and scans images for vulnerabilities before deployment.

Language specific rules

Rule 1: Respect Value Semantics

• •All arguments are passed by value.
• •Use pointers when mutating data or avoiding large copies.
• •If any method mutates a struct, all methods use pointer receivers.

Rule 2: Be Explicit About nil

• •Do not return nil slices or maps from public APIs.
• •Prefer empty slices ([]T{}) unless nil has meaning.
• •Never assume nil and empty are interchangeable.

Rule 3: Never Ignore Errors

• •Do not discard returned errors.
• •Wrap errors using %w.
• •Return errors early with contextual messages.

Rule 4: Use defer Correctly

• •defer executes at function return, not block exit.
• •Never defer inside loops unless wrapped in a function literal.
• •Place defer immediately after resource acquisition.

Rule 5: Fix Loop Variable Capture

• •Note: Go 1.22+ fixed this issue by scoping loop variables per-iteration by default.
• •For Go <1.22: Never capture loop variables directly in closures or goroutines.
• •For Go <1.22: Always shadow loop variables inside the loop.

Rule 6: Concurrency Requires Ownership

• •Do not start goroutines without:
  • •A clear owner
  • •A termination condition
• •Avoid concurrency unless it provides real benefit.
• •Prefer simple, synchronous code by default.

Rule 7: Always Respect context.Context

• •If a function accepts context.Context, it must observe cancellation.
• •Check ctx.Done() in loops and before blocking work.
• •Never store contexts in structs.

Rule 8: Maps Are Not Thread-Safe

• •Never read and write maps concurrently without synchronization.
• •Use sync.Mutex, sync.RWMutex, or justified sync.Map.
• •Never rely on map iteration order.

Rule 9: Prefer Go Idioms Over Patterns

• •Avoid Java/C++ design patterns.
• •Prefer composition over abstraction.
• •Accept interfaces, return concrete types.
• •Keep interfaces small.
• •Use generics (Go 1.18+) for type-safe data structures, but don't over-abstract.
• •Avoid using generics when a simple interface or concrete type would suffice.

Rule 10: Optimize for Clarity, Not Cleverness

• •Write boring, explicit code.
• •Avoid over-engineering.
• •Favor readability over brevity.
• •Assume the code will be maintained by humans.

Final Constraint (Hard Rule)

If correctness, simplicity, and idiomatic Go conflict with cleverness or abstraction — choose simplicity.