Instruction file imported from ethpandaops/hermes-peer-score (.cursor/rules/code_standards.mdc). Copyright stays with the author.

Hermes Peer Score Tool - Code Standards

Follow these coding standards and conventions when working on the hermes-peer-score project.

Go Code Standards

File Organization

• Place all private application code under internal/
• Group related functionality into domain-specific packages (peer, events, reports, etc.)
• Co-locate test files with source files using *_test.go naming
• Keep interfaces alongside their implementations
• Use meaningful package names that reflect their purpose

Naming Conventions

• Use camelCase for variables and functions
• Use PascalCase for exported types and functions
• Use ALL_CAPS for constants
• Use descriptive names that clearly indicate purpose
• Prefix interface names with 'I' if needed for clarity (e.g., IPeerRepository)

Code Structure

• Define interfaces in the same package as implementations when possible
• Use dependency injection pattern with interfaces
• Implement repository pattern for data access
• Use factory patterns for complex object creation
• Keep functions focused and single-purpose

Error Handling

• Always handle errors explicitly - never ignore them
• Use descriptive error messages that include context
• Wrap errors with additional context using fmt.Errorf("operation failed: %w", err)
• Use custom error types for domain-specific errors
• Log errors at appropriate levels using logrus

Logging Standards

• Use structured logging with logrus throughout the application
• Include relevant context in log messages (peer IDs, session info, etc.)
• Use appropriate log levels:
  • Debug - Detailed debugging information
  • Info - General operational information
  • Warn - Warning conditions that don't halt execution
  • Error - Error conditions that affect functionality
  • Fatal - Critical errors that cause application termination

Configuration Management

• Use struct-based configuration with clear field names
• Validate configuration at startup
• Support both command-line flags and environment variables
• Provide sensible defaults for optional configuration
• Document all configuration options

Type Definitions

• Define domain types in dedicated types.go files
• Use composition over inheritance
• Embed interfaces when appropriate
• Use type aliases for clarity (e.g., type PeerID string)
• Add JSON tags for serializable types

Testing Standards

• Write unit tests for all business logic
• Use table-driven tests for multiple test cases
• Create test helpers in internal/test_helpers.go
• Mock external dependencies using interfaces
• Aim for high test coverage on critical paths
• Use descriptive test names that explain the scenario

Code Formatting

• Use go fmt for consistent formatting
• Use go vet to catch common errors
• Follow standard Go project layout conventions
• Keep line length reasonable (generally under 120 characters)
• Use meaningful variable names over comments when possible

Documentation Standards

Code Documentation

• Document all exported functions, types, and variables
• Use standard Go doc comment format starting with the item name
• Include examples in documentation where helpful
• Explain complex algorithms or business logic
• Document any non-obvious behavior or side effects

README and Project Documentation

• Keep README.md up to date with current functionality
• Include clear installation and usage instructions
• Document all command-line options and environment variables
• Provide examples for common use cases
• Explain validation modes and their differences

Security Standards

• Never log or commit sensitive information (API keys, tokens, etc.)
• Validate all external input
• Use secure defaults in configuration
• Handle secrets through environment variables or secure configuration files
• Be cautious with network connections and data parsing

Performance Considerations

• Use efficient data structures for large datasets
• Avoid unnecessary allocations in hot paths
• Use context.Context for cancellation and timeouts
• Profile performance-critical code paths
• Consider memory usage when processing large amounts of peer data

Git Commit Standards

• Use descriptive commit messages that explain the "why"
• Start commit messages with a verb (add, update, fix, refactor, etc.)
• Keep commit messages under 50 characters for the first line
• Include additional context in the commit body if needed
• Reference issues or pull requests when applicable

Dependency Management

• Keep dependencies minimal and well-maintained
• Pin specific versions in go.mod for reproducible builds
• Document the purpose of each major dependency
• Regularly update dependencies for security patches
• Use the built-in validation mode switching for Hermes versions