code_style_conventions

Go Style

• Use standard Go formatting: gofmt.

• Use golangci-lint for code quality (run with make go_lint).

• Provide package-level documentation that describes purpose and usage.

• Use structured logging with polylog.

• Follow Go conventions for error handling.

Naming Conventions

• Package names: lowercase, short, descriptive.

• Constants:

  • camelCase for unexported constants

  • PascalCase for exported constants

• Variables: camelCase.

• Functions:

  • PascalCase for exported functions

  • camelCase for unexported functions

• Interfaces: usually end with an -er suffix (e.g., Reader, Writer).

Metrics Conventions

• All metrics use pathProcess = "path" as subsystem.

• Define metric names as constants. Example:

const (
    requestsTotal = "requests_total"
)

• Declare package-level metric variables using Prometheus constructors.

• Register metrics in init() functions using prometheus.MustRegister().

• Publish metrics through dedicated PublishMetrics() functions.

Documentation

• Provide comprehensive comments for exported functions and types.

• Use TODO comments with assignee format:

// TODO_MVP(@username): description

• Include usage examples in comments for complex functions.

Documentation and TODO format are important for maintainability and tracking ownership.

Testing

• Unit tests should support a -short flag for quick testing.

• Provide end-to-end (E2E) tests for integration scenarios.

• Use table-driven tests for multiple test cases.

• Place tests in separate files with the _test.go suffix.