Instruction file imported from karlkyck/humansreadcode-springboot-exemplar (.github/instructions/documentation.instructions.md). Copyright stays with the author.

Documentation Guidelines

Code Documentation

Javadoc Standards

• Document all public classes, interfaces, and methods
• Use @param, @return, and @throws tags appropriately
• Include examples for complex methods
• Document the purpose, not the implementation

Inline Comments

• Explain "why" not "what" in comments
• Comment complex business logic and algorithms
• Use TODO comments for planned improvements
• Remove commented-out code before committing

API Documentation

Spring Boot APIs

• Use OpenAPI 3 annotations for REST endpoints
• Document request/response models with examples
• Include error response documentation
• Use meaningful operation IDs and descriptions

Architecture Documentation

Spring Modulith

• Generate module documentation with Documenter
• Document module boundaries and responsibilities
• Explain event flows between modules
• Include PlantUML diagrams for visualization

Database Schema

• Document table purposes in Flyway migration comments
• Use database column comments for important fields
• Maintain an up-to-date data dictionary
• Document relationships and constraints

README Standards

• Include project overview and purpose
• Document prerequisites and setup instructions
• Provide build and run commands
• Include configuration options
• Add troubleshooting section
• Link to additional documentation

Change Documentation

Commit Messages

• Use conventional commit format
• Include ticket/issue references
• Explain the reason for changes
• Keep messages concise but descriptive

Migration Documentation

• Document the purpose of each Flyway migration
• Include rollback procedures where applicable
• Explain data transformation logic
• Note performance implications for large datasets