development-standards

Instruction file imported from yoelayan/educacion-financiera (.cursor/rules/development-standards.mdc). Copyright stays with the author.

Development Standards & Code Quality

This document outlines the development standards and code quality practices for the e-learning platform.

Code Quality Tools

Python Linting & Formatting

• Ruff: Primary linter and formatter configured in pyproject.toml
• Target Python Version: 3.12
• Import Sorting: Single-line imports enforced
• Line Length: 119 characters maximum

Type Checking

• mypy: Static type checking with Django plugin
• Configuration: Defined in pyproject.toml
• Django Stubs: Enhanced type checking for Django models and views

Template Linting

• djLint: Django template linter and formatter
• Indentation: 2 spaces for HTML, CSS, and JavaScript
• Profile: Django-specific rules and formatting

Pre-commit Hooks

• Configuration: .pre-commit-config.yaml
• Automatic: Runs linting, formatting, and basic checks before commits

Testing Standards

Test Framework

• pytest: Primary testing framework with Django integration
• Configuration: --ds=config.settings.test --reuse-db --import-mode=importlib
• Coverage: Django coverage plugin enabled

Test Organization

• Location: Tests should be in tests.py or test_*.py files within each app
• Coverage: Aim for high test coverage, excluding migrations
• Database: Use --reuse-db for faster test runs

Running Tests

# Run all tests
pytest

# Run with coverage
coverage run -m pytest
coverage html

Django Best Practices

Model Guidelines

• Use descriptive field names and model names
• Add __str__ methods for better admin representation
• Use model validation and custom managers when appropriate
• Optimize queries with select_related and prefetch_related

View Guidelines

• Keep views lightweight - business logic belongs in models or forms
• Use class-based views for complex functionality
• Use function-based views for simple operations
• Implement proper error handling and validation

URL Patterns

• Use descriptive URL names
• Group related URLs in app-specific urls.py files
• Follow RESTful conventions for API endpoints
• Reference: config/urls.py

Security Practices

• Always use Django's CSRF protection
• Validate and sanitize user input
• Use Django's built-in authentication system
• Follow OWASP security guidelines

File Organization

App Structure

Each Django app should follow this structure:

app_name/
├── __init__.py
├── admin.py          # Admin interface configuration
├── apps.py           # App configuration
├── models.py         # Database models
├── views.py          # View logic
├── urls.py           # URL patterns
├── forms.py          # Form definitions (if needed)
├── serializers.py    # DRF serializers (if API app)
├── tests.py          # Test cases
├── migrations/       # Database migrations
└── templates/        # App-specific templates
    └── app_name/

Import Organization

• Standard library imports first
• Third-party imports second
• Django imports third
• Local application imports last
• Use absolute imports for clarity

Performance Guidelines

Database Optimization

• Use database indexes for frequently queried fields
• Optimize queries with select_related and prefetch_related
• Use database-level constraints when possible
• Monitor query performance in development

Caching Strategy

• Use Django's caching framework for expensive operations
• Cache template fragments for dynamic content
• Consider Redis for session storage and caching

Static Files

• Optimize images and assets
• Use Django's static file management
• Consider CDN for production deployments

Documentation Standards

Code Documentation

• Use docstrings for all classes and functions
• Follow Google or NumPy docstring conventions
• Document complex business logic
• Keep comments up-to-date with code changes

API Documentation

• Use Django REST Framework's built-in documentation
• Document all API endpoints and parameters
• Provide example requests and responses