django

django Best Practices

This guide outlines the definitive best practices for developing Django applications, ensuring maintainability, performance, and security. Adhere to these rules for consistent, high-quality code.

1. Code Organization & Project Structure

Adopt the src-layout for clear separation of concerns. Keep apps focused on a single domain.

• Project Layout (src-layout):

  .
  ├── manage.py
  ├── src/
  │   ├── config/             # Project-level settings, URLs, WSGI/ASGI
  │   │   ├── __init__.py
  │   │   ├── settings/
  │   │   │   ├── __init__.py
  │   │   │   ├── base.py
  │   │   │   ├── development.py
  │   │   │   └── production.py
  │   │   └── urls.py
  │   ├── apps/               # Domain-driven Django apps
  │   │   ├── users/
  │   │   │   ├── models.py
  │   │   │   ├── views.py
  │   │   │   └── tests/
  │   │   ├── products/
  │   │   └── ...
  │   └── common/             # Reusable utilities, abstract base models, etc.
  └── requirements.txt
  

• Split Settings: Use django-environ for environment-specific settings. Never commit secrets.

  ❌ BAD: Hardcoding secrets, single settings.py

  # config/settings.py
  DEBUG = True
  SECRET_KEY = 'super-secret-dev-key'
  DATABASES = {'default': {'ENGINE': 'django.db.backends.sqlite3', 'NAME': BASE_DIR / 'db.sqlite3'}}
  

  ✅ GOOD: Environment variables, split files

  # src/config/settings/base.py
  import environ
  env = environ.Env()
  environ.Env.read_env() # reads .env file
  
  SECRET_KEY = env('SECRET_KEY')
  DEBUG = env.bool('DEBUG', default=False)
  ALLOWED_HOSTS = env.list('ALLOWED_HOSTS', default=[])
  
  # src/config/settings/development.py
  from .base import *
  DEBUG = True
  DATABASES = {'default': env.db('DATABASE_URL', default='sqlite:///db.sqlite3')}
  
  # .env file (not committed to VCS)
  SECRET_KEY=your_actual_secret_key
  DEBUG=True
  DATABASE_URL=postgres://user:pass@host:port/dbname