В начале своей карьеры в области IT большинство разработчиков выполняют простые, незначительные задачи. Такой подход принят для того, чтобы ввести сотрудника в проект, а также постепенно наращивать технические и социальные навыки. Так, поэтапно, сотрудник из рядового стажера, выполняющего «мартышкин труд», вырастает до настоящего специалиста, который приносит пользу команде. 

В то же время с ростом навыков увеличивается и сложность задач. Сначала они достаточно простые, в них из постановки ясно, что нужно сделать. Далее становится сложнее. Одного названия задачи недостаточно, чтобы понять, что требуется. На помощь обычно приходит более опытный член команды, который сможет объяснить, что к чему. 

В какой-то момент «бывший стажер» сам становится этим самым членом команды. Прорабатывать требования и решение задачи теперь необходимо самому. И тут начинают возникать следующие вопросы:

1. Как понять, что твоё решение действительно оптимальное?

2. Как объяснить другим своё решение?

3. Как сохранить описание и алгоритм работы решения для дальнейшего возможного переиспользования?

На все эти вопросы призван ответить проект фичи: описание решения задачи без подробностей реализации. Я расскажу про свой опыт решения задач с таким подходом и как это отражалось на работе нашей команды.

Как это было принято в нашей команде? 

• Решения о необходимости проектирования задачи обсуждалось заранее, на этапе планирования спринта. 

• Проект являлся полноценной отдельной задачей, требующей оценки. 

• Проект, как и обычная задача, проходил рецензирование. К проверке подключались наиболее компетентные в проекте коллеги: senior, тимлиды и архитекторы команды (если таковые есть).

• Документирование велось в Atlassian Confluence, там есть широкий спектр подходящих инструментов и макросов.

• Понимать задачу через проект гораздо проще, чем через реализацию. В то же время, многотомные проекты — тоже не лучший вариант. Задачи делились настолько мелко, чтобы проект не усложнял их, а, наоборот, дополнял и упрощал понимание. 

Инструменты для описания

Обычное текстовое описание

Самым простым способом описания вашего решения, безусловно, является текст. С его помощью можно достаточно просто и быстро набросать общие концепции решения, а также основные этапы алгоритма работы: нужно просто по пунктам перечислить то, что требуется сделать. Важно отметить, что сам проект, за некоторым исключением, практически не содержит кода. Он нужен для того, чтобы дать общее понимание решения, не вдаваясь глубоко в реализацию.

Фрагменты кода

Если всё-таки требуется уточнить какую-то подробность кода реализации, которая, например, не является очевидной, то можно воспользоваться фрагментами кода. В них, например, можно вложить заранее подготовленный SQL-запрос, или подчеркнуть особенности реализации на конкретной платформе

UML-диаграмма классов

Визуализация почти всегда усваивается проще, чем текстовое описание, но совсем заменить его вряд ли может. В список удобных визуальных отображений отношений между любыми сущностями точно можно добавить диаграмму классов. Она хорошо подходит для визуализации следующих задач:

• Описание отношений между сущностями в БД.

• Проецирование паттернов проектирования в конкретном случае.

UML достаточно удобно рисовать в https://draw.io. Там есть нужный набор блоков и разные стрелки для отображения зависимостей.

Sequence-диаграмма

Теперь ясно, как отображать отношения между классами. Но как они друг с другом взаимодействуют иногда все же остается загадкой. На подобные вопросы хорошо помогает ответить sequence‑диаграмма — она отображает последовательности вызовов разных компонентов (синхронно или асинхронно). 

Могу порекомендовать https://sequencediagram.org/. Сервис позволяет в текстовом формате отобразить sequence-диаграмму, есть много возможностей.

Блок-схема

А что делать с описанием сложных алгоритмов? Диаграмма классов не способна отображать последовательности шагов, а sequence-диаграмма больше подходит для отображения взаимодействий разных компонентов. При попытке отобразить в этом формате шаги сложного алгоритма получится каша.

В этом случае сдуваем пыль со старого, но проверенного способа — блок‑схемы алгоритмов. Такое отображение в простом формате «кубиков», «ромбиков» и «стрелок» легко раскладывает сложный алгоритм на шаги. Реализовывать его по такой схеме становится проще простого. Также могу порекомендовать использовать https://draw.io.

Визуальный стиль и разграничения

Даже если воспользоваться всеми инструментами для описания, максимально перенести текст в картинки для упрощения, то проект всё равно иногда остаётся сложным для понимания. И дело может быть в том, что в материале отсутствует структура как таковая: информация перемешана, отсутствует последовательность повествования. За этим тоже стоит следить — начинать с мелких, несвязанных вещей, чтобы позже объединить их в единое целое. Идти от частного к общему. 

Как принести такой подход в команду?

Такой подход к решению комплексных задач нравится и подходит далеко не всем командам. В то же время, я бы рекомендовал в качестве эксперимента попробовать применить этот инструмент на какой‑нибудь неприоритетной задаче и позволить команде взвесить все «за» и «против». По собственному опыту могу выделить следующие преимущества и недостатки подхода:

• Экономия времени до реализации. Автор проекта глубоко погружается в задачу, способен до реализации взвесить сильные и слабые стороны тех или иных решений, а также задокументировать их в понятной и простой форме.

• Экономия времени во время реализации. Если на задачу имеется подготовленное, заранее описанное и согласованное решение, то автору реализации нет необходимости верхнеуровнево оценивать возможные пути реализации, за него это уже сделано. Остаётся только идти по «протоптанной тропинке» и решать задачу на уровне реализации в коде.

• Экономия времени после реализации. Например, во время ревью пулл-реквеста, у ревьюера есть возможность оценить не только стилистическое соответствие кода стандартам команды, но и проверить непосредственно логику работы. Для этого нужно обратиться к проекту и просто сверить, соответствует ли ему код.

• В оценку фичи необходимо закладывать написание проекта. Есть команды, и их большинство на рынке, в которых разработка ведётся достаточно быстро и чисто физически нет времени заниматься подобными задачами. 

• Любая документация устаревает, и проект функционльности не исключение. И пытаться держать его в актуальном состоянии нет никакого смысла: на это будет уходить много времени, а польза от этого неявная. К тому же в некоторых командах ведут одну-единственную версию документации, но это противоречит общей идее технического проектирования.

• Требуется время на то, чтобы команда свыклась с таким подходом. Если она не очень гибкая с точки зрения внедрения новых практик, или этот инструмент не всем по душе, то полноценная его интеграция в рабочий процесс становится под вопросом.

Как рецензировать проект?

Во время рецензирования проекта стоит уделить внимание следующим вещам:

1. Проект в полной мере выполняет то, что поставлено в задаче? Этот пункт имеет самый высокий приоритет. Насколько бы крутое решение вы не придумали, если оно не отвечает поставленным требованиям — оно не подходит. В первую очередь необходимо делать упор на то, чтобы решение удовлетворяло всем функциональным требованиям, которые к нему предъявлены.

2. Проект оптимально решает задачу? Важно, чтобы описанное решение было достаточно эффективным, чтобы справляться с нагрузкой, то есть удовлетворяло всем нефункциональным требованиям. Помните о граничных случаях, которые также необходимо предусмотреть!

3. Проект написан понятным языком? Стоит уделить внимание тому, чтобы формулировки в проекте были ясными и однозначными. Чем лучше в этом плане описано решение, тем качественнее и точнее получится реализация и тем меньше ошибок придётся править в будущем. 

Пример проекта

Вот пример проекта задачи по отправке уведомлений в сервисе.

Заключение

Я постарался подробно рассказать про опыт проектирования технических задач в моей команде. Такой подход имеет свои достоинства и недостатки. Непосредственно результат зависит от вовлечённости и инициативы каждого члена команды.

В результате внедрения проектирования фич в нашей команде кратно возросло общее понимание проекта в целом, а также отдельных его механизмов у всех членов команды. Также у самого проекта появилась обширная и подробная документация реализованных технических решений. 

А какой у вас подход к выполнению нетривиальных и крупных задач? Пожалуйста, расскажите о нём в комментариях!