Основа качественной кодовой базы

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

Большинство инженеров-программистов хотя бы раз в своей карьере участвуют в подобных встречах по усовершенствованию. Низкое качество или неполные пользовательские истории - основная причина этих ужасных встреч.

В этой статье рассказывается, как создавать качественные пользовательские истории и почему важно овладеть этим навыком.

Что делает пользовательскую историю качественной?

Качественная пользовательская история всегда соответствует следующим требованиям:

  • это исследовано;
  • он обеспечивает контекст;
  • легко читать.

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

Исследовать

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

Всегда проверять

Юджин Льюис Фордсворте однажды сказал: «Предположения - мать всех ошибок». Хотя позже он исправил это утверждение, я все же считаю, что делать предположения во время разработки программного обеспечения опасно.

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

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

Сосредоточьтесь на главном

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

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

Улучшить оценки

Некоторые истории сложно оценить. Вы можете повысить точность оценки, задокументировав результаты своих исследований.

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

Полезные ресурсы

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

Обеспечьте контекст

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

Начни с почему

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

Если окажется, что сложно описать часть «почему» в двух предложениях, было бы неплохо разделить пользовательскую историю на несколько более мелких историй.

Большая картинка

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

Описание большого изображения должно отвечать на такие вопросы, как: Как эта функция вписывается в текущий ландшафт? Будем ли мы расширять эту функцию в будущем? Является ли эта функция частью более крупного плана?

Сделайте это легким для чтения

Люди отвлекаются, если ваша пользовательская история выглядит сложной и болезненной для чтения. Шансы на отличное уточняющее обсуждение невелики, если ваш коллега прочитает только половину текста.

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

Отдельные разные разделы

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

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

Блоки кода и имена переменных

Технические пользовательские истории часто содержат примеры кода. Без форматирования код читается с трудом. Вы можете улучшить читаемость фрагментов кода, разместив их в блоках кода или в GitHub gists. Если возможно, включите подсветку синтаксиса. Это упростит чтение ваших примеров кода.

Аналогичная концепция применяется к именам переменных, именам методов и именам классов. Без форматирования их трудно отличить от обычного текста. Элегантный вариант - отформатировать эти имена like this.

Терминология

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

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

Заключительные мысли

Следуя некоторым простым рекомендациям, можно создавать высококачественные пользовательские истории. Как мы видели в этой статье, качественные пользовательские истории имеют множество преимуществ.

Если заранее провести исследование, у вас будет больше шансов найти долгосрочное решение и снизить риск потери времени. Любой может понять пользовательские истории, содержащие контекст, что способствует эффективному обсуждению во время уточнения. Делая их легко читаемыми, вы позволяете своей команде сосредоточиться на содержании, а не отвлекаться на огромную стену текста.

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

Спасибо за прочтение. Я надеюсь, что это было полезно. Если у вас есть вопросы или отзывы, не стесняйтесь оставлять ответ.