go-style-guide

:orphan:

.. meta::
   :description: Go coding style guide covering error handling, naming
                 conventions, code structure, testing patterns, and architecture
                 principles derived from PR discussions and contribution standards.

Go coding style guide

This style guide documents Go-specific coding conventions used in the project. It captures patterns from code review discussions in merged PRs and established project standards. These guidelines complement general coding standards for your organization with project-specific decisions.

The guide is evidence-based, derived from actual PR discussions between maintainers (primarily @dmitry-lyfar and @jonathan-conder) during code reviews.

---

Error handling

Error message format

Pattern: Error messages start lowercase, contain no trailing punctuation, and follow the template: "what was attempted: why it went wrong".

Exception: Proper nouns (like "COMPONENT", "SERVICE") may start with a capital letter.

Rationale: Maintains consistency with existing error handling patterns and provides clear, actionable user guidance.

Good:

// From cmd/tool/connect.go
return fmt.Errorf("cannot connect plugs and slots across different environments")

// From cmd/tool/list.go
return fmt.Errorf("cannot list: \"--project\" incompatible with \"--global\"")

// From internal/daemon/api_environments.go
return statusBadRequest("project-id required")

Avoid:

return fmt.Errorf("Cannot connect plugs.") // Starts with capital, has punctuation
return fmt.Errorf("Error") // Not descriptive enough

---

Error specificity

Pattern: Return specific errors where possible to allow callers to handle them appropriately.

Good:

if _, err := os.Stat(path); err != nil {
    if os.IsNotExist(err) {
        // Handle file not found specifically
        return fmt.Errorf("configuration file %q not found", path)
    }
    return fmt.Errorf("cannot access configuration file %q: %w", path, err)
}