diff --git a/content/code-style.en.md b/content/code-style.en.md index 4a28c6d..dee9aea 100644 --- a/content/code-style.en.md +++ b/content/code-style.en.md @@ -113,3 +113,27 @@ I leave code cleaner than I found it. There's no need to rewrite everything at o - Commit messages in the conventional commits format: `feat:`, `fix:`, `refactor:`, `docs:`, `chore:`. - Code that doesn't pass the linter and tests doesn't get into the main branch. - Secrets, keys and `.env` never get into the repository. + +## 10. Packages + +- **Every package has a `README.md`.** It says why the package exists and what problem it solves. You open the folder and understand what's inside without reading the code. +- **The programming interface lives in an `api` module.** If other code uses the package, everything meant to be called from outside is collected in `api`. The rest of the package's modules are internal: other code doesn't reach into them, and I can change them without worrying about the package's users. If no code calls the package, it doesn't need `api`. + +### Django packages + +A Django app gets this set of modules: + +- **`settings`, always.** The list of every setting the package understands, with defaults and documentation for each. Inside the package, settings are read only from here, not through `django.conf.settings` scattered across the code. To find out how to configure the package, one file is enough. +- **`urls`, if the package has views.** The package's routes; the project plugs them in with `include()`. +- **`api`, if other code calls the package.** Following the rule above. + +```python +# reports/settings.py +from django.conf import settings + +# How many days to keep generated reports. After that they are deleted. +REPORTS_TTL_DAYS = getattr(settings, "REPORTS_TTL_DAYS", 30) + +# Address that report emails are sent from. +REPORTS_FROM_EMAIL = getattr(settings, "REPORTS_FROM_EMAIL", settings.DEFAULT_FROM_EMAIL) +``` diff --git a/content/code-style.md b/content/code-style.md index d2a3abd..a3d5d11 100644 --- a/content/code-style.md +++ b/content/code-style.md @@ -113,3 +113,27 @@ Docstring обязателен для публичных функций и кл - Сообщение коммита в формате conventional commits: `feat:`, `fix:`, `refactor:`, `docs:`, `chore:`. - В основную ветку не попадает код, который не проходит линтер и тесты. - Секреты, ключи и `.env` никогда не попадают в репозиторий. + +## 10. Пакеты + +- **В каждом пакете есть `README.md`.** В нем написано, зачем пакет существует и какую задачу решает. Открыл папку и сразу понял, что внутри, без чтения кода. +- **Программный интерфейс живет в модуле `api`.** Если пакетом пользуются из другого кода, все, что можно вызывать снаружи, собрано в `api`. Остальные модули пакета внутренние: другой код в них не лезет, и я могу менять их, не оглядываясь на тех, кто пакетом пользуется. Если пакет никто не вызывает из кода, `api` не нужен. + +### Django-пакеты + +Для Django-приложения набор модулей такой: + +- **`settings`, всегда.** Перечень всех настроек, которые пакет понимает, с умолчаниями и документацией к каждой. Внутри пакета настройки берутся только отсюда, а не через `django.conf.settings` вразброс по коду. Чтобы узнать, как настроить пакет, достаточно открыть один файл. +- **`urls`, если у пакета есть вьюхи.** Маршруты пакета, проект подключает их через `include()`. +- **`api`, если к пакету обращаются из кода.** По правилу выше. + +```python +# reports/settings.py +from django.conf import settings + +# Сколько дней хранить сформированные отчеты. После этого срока они удаляются. +REPORTS_TTL_DAYS = getattr(settings, "REPORTS_TTL_DAYS", 30) + +# Адрес, с которого уходят письма с отчетами. +REPORTS_FROM_EMAIL = getattr(settings, "REPORTS_FROM_EMAIL", settings.DEFAULT_FROM_EMAIL) +```