The following text is a partial translation of the original English article, performed by ChatGPT (gpt-3.5-turbo) and this Jekyll plugin:
Есть отличная книга под названием Требования к программному обеспечению, написанная Карлом Вигерсом о, ну, требованиях к программному обеспечению. По моему мнению, это обязательное чтение для каждого программного инженера. Нет необходимости повторять то, что она говорит, но мы продолжаем делать несколько очень простых и типичных ошибок в наших спецификациях. Я вижу их снова и снова в наших документах, и поэтому я решил их подвести и суммировать. Итак, вот они, десять самых критических и типичных, с точки зрения программиста, читающего спецификационный документ.
Глава 4.3 известного стандарта IEEE 830-1998 говорит, что хорошая спецификация должна быть правильной, недвусмысленной, полной, согласованной, рейтинговой, проверяемой, изменяемой и прослеживаемой. Всего восемь качеств. Затем стандарт объясняет их одно за другим на простом английском языке. Но есть ли у нас время читать эти скучные стандарты? Они предназначены для университетских профессоров и сертификационных комиссий. Мы практики, черт возьми! … Подождите, я шучу.
Независимо от размера проекта и нашей практичности, всегда есть документ, который объясняет, что нужно сделать, и его можно называть “спецификацией требований к программному обеспечению”, или “спецификацией”, или просто “спекой”. Конечно, есть много места для креативности, но мы инженеры, а не художники. Мы должны следовать правилам и стандартам, в основном потому, что они облегчают наше общение.
Теперь я перехожу к сути. Спецификации, которые я обычно вижу, нарушают практически все восемь принципов, упомянутых ранее. Внизу приведено краткое изложение, как именно они это делают. Кстати, все примеры взяты из реальных документов реальных коммерческих программных проектов.
How about this:
UUID is set incrementally to make sure there
are no two users with the same account number.
В чем разница между UUID и номером аккаунта? Это одно и то же? Кажется, да, верно? Или, может быть, они отличаются… было бы здорово знать, что означает UUID. Это “уникальный идентификатор пользователя” или, может быть, “объединенный дескриптор идентичности пользователя”? У меня нет идей. Я потерялся и хочу найти автора этого текста и сделать ему что-то плохое… или ей.
Я уже писал, что самые плохие технические спецификации не имеют глоссариев. По моему опыту, это самая большая проблема во всех документах с требованиями. Это не проза! Это не письмо любви! Это техническая документация. Мы не можем играть словами для удовольствия. Мы не должны использовать технические характеристики просто для самовыражения. Мы пишем для того, чтобы быть понятыми, а не чтобы произвести впечатление на читателя. И та же самая правила действуют здесь, как и с диаграммами: если я вас не понимаю, это ваша вина.
Вот как выглядел бы этот текст после правильной переработки:
Better now?
Таким образом, первая и наиболее серьезная проблема заключается в бесцельном использовании терминов и просто слов, не имеющих предварительного определения в глоссарии.
Я недавно видел(а) это в спецификации продукта.
Да, этот текст дословно присутствует в документе требований. Сначала автор выражает свое личное мнение о предмете. Затем автор спрашивает меня, какие возможные варианты существуют. Потом он предлагает мне что-то рассмотреть и после этого приглашает меня на разговор.
Впечатляюще, не так ли? Очевидно, автор обладает очень творческой личностью. Но мы должны держаться этого человека как можно дальше от документации проекта. Это не то, что ценится в документе требований. Хорошо, мы ценим творчество, но эти четыре вещи строго запрещены: вопросы, обсуждения, предложения и мнения.
В спецификациях не может быть никаких вопросов. Кому адресованы эти вопросы? Мне, программисту? Я должен реализовывать программное обеспечение или отвечать на ваши вопросы? Мне не интересно с вами брейнштормить. Я ожидаю, что вы, автор требований, скажете мне, что нужно сделать. Найдите все ответы перед написанием документа. За это вам платят. Если у вас нет ответов, поставьте что-то вроде TBD (“требует определения”). Но не задавайте вопросы. Это раздражает.
Документ требований - это не форум для обсуждения. Как читатель спецификации, я ожидаю увидеть то, что нужно сделать без каких-либо “может быть” или “мы могли бы сделать иначе”. Конечно, вам нужно обсудить эти вопросы, но сделайте это до документирования. Сделайте это где-то еще, например, в Skype, на Slack или по электронной почте. Если вы действительно хотите обсудить в документе, используйте Google Docs или Word с отслеживанием версий. Но когда обсуждение закончено, удалите его историю из документа. Его наличие только запутывает меня, программиста.
Также нет необходимости форматировать требования как предложения. Просто скажите, что нужно сделать и как должно работать программное обеспечение, не боясь ошибиться. Обычно люди прибегают к предложению, когда боятся сказать прямо. Вместо того, чтобы сказать “приложение должно работать на Android 3.x и выше”, они говорят “я бы предложил сделать приложение совместимым с Android 3.x и выше”. Видите разницу? Во втором предложении автор пытается избежать личной ответственности. Он не говорит “точно Android 3.x”; он просто предлагает. Не будьте трусом, скажите прямо. Если вы сделаете ошибку, мы ее исправим.
И, конечно же, мнения не ценятся вообще. Это не письмо другу; это официальный документ, принадлежащий проекту. Через несколько месяцев или недель вы можете покинуть проект, и кто-то другой будет работать с вашим документом. Спецификация - это контракт между спонсором проекта и командой проекта. Мнение автора документа здесь не имеет значения. Вместо того, чтобы отметить “похоже, что Java будет быстрее” и предложить “мы должны использовать ее”, скажите “Java быстрее, поэтому мы должны использовать ее”. Очевидно, вы положили это туда, потому что так думаете. Но раз оно там, нам все равно, откуда оно появилось и что вы думали об этой проблеме. Информация просто запутает нас еще больше, поэтому пропустите ее. Просто факты, без мнений.
Не поймите меня неправильно, я не против творчества. Программисты не роботы, тихо реализующие то, что говорит документ. Но беспорядочный документ не имеет ничего общего с творчеством. Если вы хотите, чтобы я творил, определите границы этого творчества и позвольте мне экспериментировать в пределах этих границ; например:
Так ты приглашаешь меня быть творческим. Я понимаю, что у пользователя продукта на самом деле нет никаких обоснований или ожиданий от механизмов версионирования в API. Я свободен делать все, что мне нужно. Отлично, я сделаю это по-своему.
Но опять же, позволь мне повторить: спецификация - это не форум для обсуждений.
Вот как это выглядит:
Это типичная ошибка в почти каждой спецификации, которую я видел. Здесь мы смешиваем функциональное требование (“прокрутка изображений”) и нефункциональное требование (“прокрутка должна быть плавной и быстрой”). Почему это плохо? Ну, нет конкретной причины, но это свидетельствует о недостатке дисциплины.
Такое требование сложно проверить или протестировать, сложно проследить и сложно реализовать. Как программист, я не знаю, что важнее: прокрутка или убедиться, что прокрутка быстрая.
Кроме того, такое утверждение сложно изменить. Если завтра мы добавим еще одно функциональное требование - например, прокрутка списка друзей - мы захотим также требовать, чтобы эта прокрутка была плавной и быстрой. Затем, через несколько дней, мы захотим сказать, что “быстрая” означает менее 10 миллисекунд реакции. Придется дублировать эту информацию в двух местах. Понимаете, как неопрятным может стать наш документ со временем?
Поэтому я настоятельно рекомендую всегда документировать функциональные и нефункциональные требования отдельно.
Это похоже на предыдущую проблему и может выглядеть так:
Очевидно, что в этом абзаце описано две вещи. Первая - это возможность пользователя скачать отчет в формате PDF. Вторая - это описание вида этого отчета. Первая вещь является функциональным требованием, а вторая должна быть описана в дополнительном документе (или приложении).
В общем, функциональные требования должны быть очень краткими: «пользователь скачивает», «пользователь сохраняет», «клиент запрашивает и получает» и т. д. Если ваш текст становится слишком длинным, что-то идет не так. Попробуйте переместить часть его в дополнительный документ.
Вот о чем я говорю:
Я могу найти еще много примеров, просто открывая требования во многих проектах, которые я видел за последние несколько лет. Они все выглядят одинаково. И проблема всегда одна и та же: очень сложно определить действительно проверяемое и измеримое нефункциональное требование.
Да, это сложно. Главным образом потому, что есть много факторов. Возьмем, к примеру, эту строку: «Приложение должно запускаться за 2 секунды». На каком оборудовании? С каким объемом данных в профиле пользователя? Что означает «запуск»; включает ли это время загрузки профиля? Что, если возникнут проблемы с запуском? Они учитываются? Возникает много таких вопросов.
Если мы ответим на все из них, текст требования займет целую страницу. Никто этого не хочет, но иметь неизмеримые требования - большое зло.
Опять же, это не легко, но необходимо. Постарайтесь убедиться, что все требования к качеству полны и не имеют двусмысленности.
Этот пример иллюстрирует очень распространенное затруднение:
Это микроуправление, и это то, что аналитик по требованиям никогда не должен делать программисту. Вы не должны говорить мне, как реализовать желаемую функциональность. Вы хотите дать пользователю возможность входа через Facebook? Скажите об этом. Вам действительно важно, будет ли это происходить при нажатии кнопки или каким-то другим способом? Вам действительно важно, что я храню в базе данных? Что, если я использую файлы вместо базы данных? Это для вас важно?
Я не думаю, что это так. В очень редких случаях это имеет значение. Большую часть времени это просто микроуправление.
Спецификация должна требовать только то, что действительно важно для бизнеса. Все остальное зависит от нас, программистов. Мы решаем, какую базу данных использовать, где будет размещена кнопка и какая информация будет храниться в базе данных.
Если вам действительно важно это, потому что есть определенные ограничения более высокого уровня, скажите об этом. Но снова не в качестве инструкций по реализации для нас, программистов, а скорее в качестве нефункциональных требований, подобных этим:
Суть в том, что у меня нет ничего против требований, но я решительно против инструкций по выполнению.
Текст может выглядеть так:
Проблема здесь в том, что здесь нет “актера”. Функционал более или менее понятен, но не ясно, кто все это делает. Где находится пользователь? Это просто история того, что-то происходит где-то. Это действительно не то, что нужно программистам для его реализации.
Лучший способ объяснить функционал - через пользовательские истории. И хорошая пользовательская история всегда имеет, угадайте что … пользователя. Она всегда начинается с “пользователь …”, за которым следует глагол. Пользователь загружает, пользователь сохраняет, пользователь нажимает, печатает, удаляет, форматирует и т.д.
Не обязательно, чтобы пользователь был человеком. Это может быть система, клиент RESTful API, база данных, что угодно. Но всегда кто-то. “Возможно загрузить …” - это не пользовательская история. Это возможно для кого?
How about this:
Our primary concern is performance and an attractive
user interface.
Это шум. В качестве читателя этого документа я не являюсь инвестором или пользователем. Я программист. Мне не важно, какова ваша “основная проблема” в этом проекте. Моя задача - реализовать продукт так, чтобы он соответствовал спецификациям. Если производительность является вашей основной проблемой, создайте измеримые и проверяемые требования для меня. Я убедюсь, что продукт их удовлетворяет. Если вы не можете создать требование, не спамьте меня этой несущественной информацией.
Я не хочу разделять ваши заботы, верования или намерения. Это ваше дело. И вам платят за то, чтобы правильно и однозначно переводить все это в проверяемые и измеримые требования. Если вы не можете сделать это, это ваша проблема и ваша вина. Не пытайтесь сделать это моей.
Очень часто… подождите. Очень-очень часто. Нет. Почти всегда. Ошибка снова. Всегда! Верно, спецификации всегда полны шума. У некоторых из них может быть немного меньше, у некоторых больше. Я считаю это симптомом ленивых и непрофессиональных авторов документов. В большинстве случаев, просто ленивых.
Им не хочется думать и переводить свои заботы, идеи, мысли, намерения и цели в функциональные и нефункциональные требования. Они просто помещают их в документ и надеются, что программисты как-то найдут правильное решение. Хорошие программисты должны понять, что такое хорошая производительность, верно? Давайте просто скажем им, что производительность для нас проблема, и они что-нибудь придумают.
Нет! Не делайте так. Выполняйте свою работу правильно и позвольте программистам делать свою.
А мы, программисты, никогда не должны принимать такие документы. Мы должны просто отклонять их и просить авторов требований переработать и удалить шум. Я рекомендовал бы даже не начинать работу над продуктом, если в его спецификациях много шума.
Это еще одна очень типичная ошибка:
Видите, насколько это беспорядочно звучит? Здесь присутствуют три различные точки зрения, и ни одна из них не подходит для спецификационного документа. Спецификация должна описывать продукт так, как будто он уже существует. Спецификация должна звучать как руководство, учебник или справочник. Этот текст должен быть переписан следующим образом:
Видите разницу? Все слова “должно”, “нужно” и “будет” только добавляют сомнения в документ. Для читателя этой спецификации фраза “API будет поддерживать” звучит как “в какой-то момент в будущем, возможно, в следующей версии, оно будет поддерживать”. Это не то, что автор имел в виду, верно? Здесь не должно быть сомнений, двусмысленностей или “может быть”. API поддерживает. Вот и всё.
Я могу что-то важное забыть, но эти проблемы настолько очевидны и раздражающи… Я собираюсь использовать этот пост в качестве простого руководства для наших системных аналитиков. Не стесняйтесь делиться своим опытом работы с документацией требований в комментариях ниже.
Translated by ChatGPT gpt-3.5-turbo/42 on 2023-12-16 at 16:03
