rails-instructions rails-models.instructions.md

Rails Models and Active Record Guide

Core Philosophy

• Models are the heart of your Rails application
• Keep business logic and data integrity in models
• Use database constraints to enforce rules
• Design for clarity and maintainability
• Trust Active Record's conventions

Model Design Principles

• Focus models on their core domain responsibility
• Keep models cohesive and loosely coupled
• Use descriptive names that reflect business concepts
• Avoid God objects - split large models when needed
• Document complex business rules clearly

Schema Management

• Always use the annotate gem for schema documentation
• Keep schema annotations at the top of model files
• Run annotate after every migration
• Review schema changes carefully before committing
• Document non-obvious column purposes

Model Organization

• Order model contents consistently for readability
• Place constants at the top
• Group related elements together
• Keep public interface minimal
• Document complex logic thoroughly

Associations Best Practices

• Define all relationships explicitly
• Use appropriate dependent options
• Consider bi-directional associations carefully
• Avoid circular dependencies
• Document association purposes when not obvious

Validation Strategy

• Validate at the model level always
• Use database constraints to match validations
• Keep validation messages user-friendly
• Group related validations together
• Test all validation scenarios

Database Constraints

• Add NOT NULL constraints for required fields
• Use unique indexes for uniqueness validations
• Implement foreign key constraints
• Add check constraints for complex rules
• Document constraint purposes in migrations

Scopes and Queries

• Create scopes for commonly used queries
• Keep scope names descriptive and intention-revealing
• Chain scopes for complex queries
• Avoid scopes with side effects
• Use class methods for scopes with parameters

Callbacks Guidelines

• Use callbacks sparingly and purposefully
• Keep callback methods private
• Avoid callbacks that touch other models
• Document callback purposes clearly
• Consider service objects for complex workflows