На днях в канале настенька и графики моей бывшей коллеги и друга Насти увидел пост про важность объяснений "почему" мы делаем так, а не иначе. Обычное "что" надо сделать — приносит мало пользы.
И правда, объяснять зачем — это не просто хороший тон, это необходимость. Особенно когда работаешь в команде или над проектом, который будет жить долго.
Вот несколько примеров из разных аспектов айтишечки, где этот принцип работает на все 100:
📚 Документация
❌ Плохо:
API-метод /payments/cancel отменяет платежи
Это и так видно из названия. Зачем он нужен? В каких случаях использовать?
✅ Хорошо:
Метод /payments/cancel отменяет платежи до их подтверждения банком (статус pending). Используется, если пользователь передумал сразу после оплаты. Не работает для уже проведенных платежей (статус completed)
Почему это важно?
— Новые разработчики не потратят часы на тестирование "нерабочего" метода.
— QA поймет, какие сценарии проверять.
📋 Постановка задач
❌ Плохо:
Добавить поле 'регион' в форму регистрации
Зачем? Может, это требование GDPR? Или маркетинг хочет аналитику?
✅ Хорошо:
Добавить поле 'регион' в форму регистрации:
— Для пользователей из ЕС — обязательное (требования GDPR).
— Для остальных — опциональное (поможет в локализации)
Почему это важно?
— Разработчик не будет гадать, где поле должно быть обязательным.
— Тестировщик сразу поймет, какие кейсы проверять.
🔀 Pull Request'ы
❌ Плохо:
Исправил баг с авторизацией
Какой баг? Почему решение верное?
✅ Хорошо:
Исправил баг с авторизацией:
— Проблема: Токен обновлялся даже при неактивной сессии (ошибка 401).
— Решение: Добавил проверку session.isActive() перед обновлением.
— Почему это безопасно: Метод isActive() покрыт интеграционными тестами
Почему это важно?
— Ревьювер не утонет в догадках, а быстро проверит логику.
— Через месяц вы сами вспомните, почему сделали именно так.
👥 Встречи и обсуждения
❌ Плохо:
Нужно переписать модуль X на Go
Почему не Python? Это критично для дедлайна?
✅ Хорошо:
Переписываем модуль X на Go:
— Причина: Текущая реализация на Python не справляется с нагрузкой > 10k RPS.
— Альтернативы: Рассмотрели кеширование, но это лишь временное решение.
— Риски: Миграция займет 2 недели, но снизит затраты на инфраструктуру.
Почему это важно?
— Команда видит, что решение взвешенное, а не "просто ради Go".
— Новые участники поймут контекст, даже пропустив обсуждение.
👀 Тестирование
❌ Плохо:
Тест: проверить отправку email после регистрации
Какой email? Всем ли пользователям?
✅ Хорошо:
Тест: проверить отправку email после регистрации:
— Кейс: Письмо с подтверждением отправляется только новым пользователям (поле is_new=True).
— Почему: Спам-фильтры банят, если отправлять повторно
Почему это важно?
Тестировщик не потратит время на проверку "почему письмо не пришло".
🪄 Лайфхаки
— Везде, где возможно, добавляйте ссылки на контекст: задачи в таск-трекере, страницы в вики, чаты в телеграм.
— Если решение временное, пишите FIXME/TODO + дату:
// TODO: Удалить после миграции на Logbroker (дедлайн: 01.01.2024) — В сложных решениях оставляйте аргументы против альтернатив (например, "Выбрали Redis вместо Memcached из-за поддержки TTL на уровне ключей").
💡 Итого
Чем больше вы объясняете зачем, тем меньше времени команда тратит на "догадки" и тем выше качество продукта.
#softskills #management #bestpractices