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.

Basic rules

Language specific rules

Rule 1: Respect Value Semantics

Rule 2: Be Explicit About nil

Rule 3: Never Ignore Errors

Rule 4: Use defer Correctly

Rule 5: Fix Loop Variable Capture

Rule 6: Concurrency Requires Ownership

Rule 7: Always Respect context.Context

Rule 8: Maps Are Not Thread-Safe

Rule 9: Prefer Go Idioms Over Patterns

Rule 10: Optimize for Clarity, Not Cleverness

Final Constraint (Hard Rule)

Rule 2: Be Explicit About `nil`

Rule 4: Use `defer` Correctly

Rule 7: Always Respect `context.Context`

golang

Go patterns