go-coding-standards

Go Coding Standards

Project Structure and Organization

• Group code by feature/domain when appropriate (agent, task, tool, workflow)
• Keep package names simple and descriptive
• Follow the established pattern of separating interfaces from implementations

Code Style and Standards

<documentation_policy>

• DON'T ADD comments to explain code changes - explanation belongs in text responses
• Only add code comments when user explicitly requests them or code is complex and requires context for future developers </documentation_policy>

Error Handling

<unified_strategy type="mandatory"> UNIFIED ERROR HANDLING STRATEGY - SINGLE SOURCE OF TRUTH

1. Internal Error Propagation (within domains):

   • Use fmt.Errorf() for all internal error propagation within a domain
   • Always wrap errors with context: fmt.Errorf("failed to load user: %w", err)
   • This keeps internal code simple and avoids unnecessary abstraction

2. Domain Boundaries (public service methods):

   • Use core.NewError() ONLY when returning errors from public service methods
   • These are the methods exposed to other domains or external consumers
   • Provides structured error information for cross-domain communication

3. Always Required:

   • Check and handle errors explicitly - never ignore errors
   • Return early on errors to avoid deep nesting
   • Avoid naked returns in longer functions (as enforced by nakedret linter) </unified_strategy>

// ✅ DOMAIN BOUNDARY: Use core.NewError for public methods func (s *userService) CreateUser(ctx context.Context, req CreateUserRequest) (*User, error) { user := &User{Email: req.Email, Name: req.Name} if err := s.validateUser(ctx, user); err != nil { return nil, core.NewError(err, "USER_VALIDATION_FAILED", map[string]any{ "email": req.Email, }) } // ... rest of implementation using fmt.Errorf internally }

</examples>