Go Coding Standards

Basic Principles

One Function, One Responsibility

• If function name connects with "and" or "or", it's a signal to split
• If test cases are needed for each if branch, it's a signal to split

Conditional and Loop Depth Limited to 2 Levels

• Minimize depth using early return whenever possible
• If still heavy, extract into separate functions

Make Function Side Effects Explicit

• Example: If getUser also runs updateLastAccess(), specify it in the function name

Convert Magic Numbers/Strings to Constants When Possible

• Declare at the top of the file where used
• Consider separating into a constants file if there are many

Function Order by Call Order

• Follow Go's clear conventions if they exist
• Otherwise, order top-to-bottom for easy reading by call order

Review External Libraries for Complex Implementations

• When logic is complex and tests become bloated
• If industry-standard libraries exist, use them
• When security, accuracy, or performance optimization is critical
• When platform compatibility or edge cases are numerous

Modularization (Prevent Code Duplication and Pattern Repetition)

• Absolutely forbid code repetition
• Modularize similar patterns into reusable forms
• Allow pre-modularization if reuse is confirmed
• Avoid excessive abstraction
• Modularization levels:
  • Same file: Extract into separate function
  • Multiple files: Separate into different package
  • Multiple projects/domains: Separate into different module

Variable and Function Names

• Clear purpose while being concise
• Forbid abbreviations outside industry standards (id, api, db, err, etc.)
• Don't repeat context from the parent scope
• Boolean variables use is, has, should prefixes
• Function names are verbs or verb+noun forms
• Plural rules:
  • Pure arrays/slices: "s" suffix (users)
  • Wrapped struct: "list" suffix (userList)
  • Specific data structure: Explicit (userSet, userMap)
  • Already plural words: Use as-is

Field Order

• Alphabetically ascending by default
• Maintain consistency in usage

Error Handling

• Error handling level: Handle where meaningful response is possible
• Error messages: Technical details for logs, actionable guidance for users
• Error classification: Distinguish between expected and unexpected errors
• Error propagation: Add context when propagating up the call stack
• Recovery vs. fast fail: Recover from expected errors with fallback
• Use %w for error chains, %v for simple logging
• Wrap internal errors not to be exposed with %v
• Never ignore return errors from functions; handle them explicitly
• Sentinel errors: For expected conditions that callers must handle, use var ErrNotFound = errors.New("not found")

File Structure

Element Order in File

1. package declaration
2. import statements (grouped)
3. Constant definitions (const)
4. Variable definitions (var)
5. Type/Interface/Struct definitions
6. Constructor functions (New*)
7. Methods (grouped by receiver type, alphabetically ordered)
8. Helper functions (alphabetically ordered)

Interfaces and Structs

Interface Definition Location

• Define interfaces in the package that uses them (Accept interfaces, return structs)
• Only separate shared interfaces used by multiple packages

Pointer Receiver Rules

• Use pointer receivers for state modification, large structs (3+ fields), or when consistency is needed
• Use value receivers otherwise

Context Usage

Context Parameter

• Always pass as the first parameter
• Use context.Background() only in main and tests

Testing

Testing Libraries

• Prefer standard library's if + t.Errorf over assertion libraries like testify
• Prefer manual mocking over gomock

Forbidden Practices

init() Functions

• Avoid unless necessary for registration patterns (database drivers, plugins)
• Prefer explicit initialization functions for business logic
• Acceptable uses:
  • Driver/plugin registration (e.g., database/sql drivers)
  • Static route/handler registration with no I/O
  • Complex constant initialization without side effects
• Forbidden uses:
  • External I/O (database, file, network)
  • Global state mutation
  • Error-prone initialization (use constructors that return errors)

Package Structure

internal Package

• Actively use for libraries, use only when necessary for applications

Recommended Libraries

• Web: chi
• DB: Bun, SQLBoiler (when managing migrations externally)
• Logging: slog
• CLI: cobra
• Utilities: samber/lo, golang.org/x/sync
• Configuration: koanf (viper if cobra integration needed)
• Validation: go-playground/validator/v10
• Scheduling: github.com/go-co-op/gocron
• Image processing: github.com/h2non/bimg