ira/.note/development_standards.md

Development Standards

Coding Conventions

Python Style

• Follow PEP 8 style guidelines for Python code
• Use 4 spaces for indentation (not tabs)
• Maximum line length of 79 characters
• Use docstrings for all modules, classes, and functions
• Include type hints for function parameters and return values

Documentation

• All modules should have a module-level docstring explaining their purpose
• All functions and classes should have docstrings following the Google style:
  • Brief description
  • Args section with parameter descriptions
  • Returns section describing return values
  • Raises section for exceptions that might be raised

Error Handling

• Use custom exception classes for domain-specific errors (e.g., TokenLimitError)
• Handle exceptions at appropriate levels
• Provide informative error messages
• Log errors with sufficient context for debugging

Project Structure

• Keep modules focused on a single responsibility
• Separate API interaction from business logic
• Use environment variables for configuration and secrets
• Include sample files for testing and demonstration

Testing

• Write unit tests for core functionality
• Include integration tests for API interactions
• Use sample files for consistent test cases
• Test error handling and edge cases

API Usage

• Always include proper authentication headers
• Handle API rate limits and errors gracefully
• Document API dependencies and version requirements
• Include comments with links to API documentation

Security

• Never hardcode API keys or credentials
• Use environment variables for sensitive information
• Validate and sanitize inputs
• Handle errors without exposing sensitive information