Топ Советов по Повышению Продуктивности. Часть 4
Части 1, 2, 3
4. Разработка, основанная на документации: пишите документацию до написания кода
Звучит нелогично, пока вы не попробуете.
Традиционный рабочий процесс разработчика: написать код, заставить его работать, отполировать его, а затем (возможно, если кто-то напомнит вам или есть контрольный список для PR) написать документацию, объясняющую, что вы только что создали. Документация — это результат разработки, овощи, которые вы едите, потому что они полезны, а не потому что хотите.
Сделайте наоборот. Прежде чем писать код реализации, напишите документацию о том, как будет работать функция или API. Опишите, что она делает, какие параметры принимает, что возвращает, какие граничные случаи обрабатывает и как её использовать.
Преимущества
1. Мгновенная ясность
Написание документации заставляет продумывать детали так, как это никогда не происходит при написании кода. Вы обнаружите проблемы проектирования до того, как их будет дорого исправлять. «А что произойдет, если клиент передаст null?» — вопрос, на который вы ответите на этапе проектирования, а не ошибка, обнаруженная кем-то в продакшене.
2. Улучшение API
Когда вы сначала пишете документацию с точки зрения пользователя, вы естественным образом проектируете более интуитивно понятные интерфейсы. Вы заметите непонятные имена, отсутствующие параметры или неудобные шаблоны использования, потому что придётся их пояснять в документации.
3. Упрощение реализации
Вы уже продумали логику. Документация — это ваше техзадание. Теперь просто переведите это в код. Больше не нужно смотреть на пустой файл, не зная, с чего начать.
4. Документация никогда не устаревает
Поскольку она была написана первой, она соответствует тому, что вы создали. Не нужно пытаться восстановить документацию из готового кода, где вы уже забыли половину процесса принятия решений.
Новый уровень
Для сложных функций пишите три типа документации перед написанием кода:
1. Документация для пользователя - как кто-то будет использовать эту функцию.
2. Документация API - сигнатуры функций, параметры, возвращаемые значения.
3. Журнал решений - почему вы приняли те или иные проектные решения (это бесценно для вас в будущем). См. также ADR.
Инструменты, поддерживающие этот рабочий процесс:
- Пишите документацию в формате Markdown прямо рядом с кодом.
- Храните файл
decisions.md (журнал решений) в корневой директории проекта.- Для API используйте спецификации OpenAPI/Swagger в качестве инструмента для создания документации.
Изменение мышления
Вы не разработчик, который пишет документацию. Вы дизайнер, который выражает свои замыслы как через документацию, так и через код. Документация — это не налог, который вы платите после создания чего-либо, — это план, который делает создание продукта возможным.
Попробуйте это, реализуя свою следующую задачу. Сначала README. Затем напишите описания и интерфейсы функций перед реализацией тел функций. Напишите документацию API перед реализацией конечных точек. Это кажется странным примерно 30 минут, а потом проявляется путь до самого конца, где на каждом этапе очевидно, что делать.
Источник: https://dev.to/thebitforge/top-10-productivity-hacks-every-developer-should-know-151h