Go Style Guide

Use the Go style guide to keep implementation choices boring, predictable, and easy to review.

This page captures the coding defaults maintainers expect in normal Go work: naming, error handling, logging, reconciler-safe concurrency, imports, and constants. The goal is not novelty. The goal is code that behaves like the rest of the repository.

Decision matrix

Default coding choices

Default coding choices.

Area	Expected default	Avoid
Naming	Keep acronyms consistently cased and use direct Go-style getter names.	Mixed-case acronym spellings such as ServeHttp or getters such as GetStatus().
Errors	Wrap returned errors with %w so callers keep context and error identity.	Returning opaque upstream errors with no explanation.
Logging	Use structured logr key-value logging.	fmt.Printf, log.Println, or string-built log lines that lose context.
Reconcilers	Keep work synchronous and requeue explicitly when you need another pass.	Unmanaged goroutines or time.Sleep in reconcile code.
Imports and constants	Use stable import grouping and name magic values explicitly.	Ad hoc import ordering and raw literals with unclear meaning.

Naming

• Keep acronyms consistently cased: ServeHTTP, ParseURL, userID.
• Do not prefix getters with Get.
• Prefer -er names for single-method interfaces when the interface describes capability.

Errors and logging

Use wrapped errors and structured logging together. Most reviewer comments in this area come from missing context, not from complex logic.

if err := syncSecret(ctx, obj); err != nil {
    return fmt.Errorf("sync secret for %s/%s: %w", obj.Namespace, obj.Name, err)
}

log.Info("reconciling cluster",
    "cluster_namespace", req.Namespace,
    "cluster_name", req.Name,
)

Never log secrets

Do not log tokens, keys, passwords, or raw Secret data, even in debug-only paths.

Reconcile-safe concurrency

• Do not spawn unmanaged goroutines in reconcile code.
• Do not block workers with time.Sleep.
• Use RequeueAfter when the controller should check again later.

Imports and constants

Group imports into three blocks:

1. standard library
2. third-party dependencies
3. local github.com/dc-tec/openbao-operator/... packages

Name important values explicitly instead of leaving raw numbers or suffix strings in logic.

Related standards

Error handlingOpen the error-specific rules when the question is how to preserve context, classify failure, or avoid panics.Kubernetes operator patternsUse the controller-specific guidance when the change lives in reconciliation, status, or app-layer delegation.Project conventionsGo back to the repository-level rules when the problem is scope, boundaries, or generated output.