Ten mistakes in specs

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

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

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

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

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

Нет глоссария или нечеткие определения

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

В чем разница между UUID и номером счета? Это одно и то же? Кажется, да? Или, может быть, они разные ... было бы замечательно узнать, что означает UUID. Это «уникальный идентификатор пользователя» или, может быть, «унифицированный дескриптор идентификатора пользователя»? Понятия не имею. Я потерялся, и я хочу найти автора этого текста и сделать с ним что-то плохое ... или ее.

Я уже писал, что в наихудших технических спецификациях нет глоссариев. По моему опыту, это самая большая проблема во всех необходимых документах. Это не проза! Это не любовное письмо! Это техническая документация. Мы не можем жонглировать словами ради удовольствия. Мы не должны использовать спецификации продукта только для того, чтобы выразить себя. Мы пишем для того, чтобы быть понятыми, а не для того, чтобы произвести впечатление на читателя. И правило здесь такое же, как и в случае с диаграммами: если вас не понимают, это ваша вина.

Вот как этот текст будет выглядеть после надлежащей перезаписи:

UUID - уникальный идентификатор пользователя, положительное целое 4 байта.

UUID устанавливается пошагово, чтобы не быть установленными пользователями с одинаковым UUID.

Теперь лучше?

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

Вопросы, обсуждения, предложения, мнения

Я видел это совсем недавно в спецификации продукта:

Я считаю, что должны поддерживаться несколько версий API . Какие у нас есть варианты? Я предлагаю перейти с версиями URL-адресов. Не стесняйся публиковать свои мысли здесь.

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

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

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

В спецификациях не может быть никаких вопросов. К кому относятся эти вопросы? Я, программист? Я должен реализовать программное обеспечение или ответить на ваши вопросы? Меня не интересует мозговой штурм с вами. Я ожидаю, что вы, автор требований, расскажите мне, что нужно сделать. Прежде чем писать документ, найдите все ответы на свои вопросы. Это то, за что вам платят. Если у вас нет ответов, поместите там что-то вроде TBD («будет определено»). Но не задавай вопросов. Это раздражает.

Документ требований не является доской обсуждений. Как читатель спецификации, я ожидаю увидеть, что именно нужно сделать без «возможно» или «мы могли бы сделать это по-другому». Конечно, вам нужно обсудить эти проблемы, но сделайте это, прежде чем документировать. Сделайте это где-нибудь в другом месте, например, в Skype, в Slack или по электронной почте. Если вы действительно хотите обсудить в документе, используйте Google Docs или Word с отслеживанием версий. Но когда обсуждение закончено, удалите его историю из документа. Его присутствие только смущает меня, программиста.

Нет необходимости форматировать требования как предложения. Просто скажите, что нужно сделать и как программное обеспечение должно работать, не опасаясь быть неправым. Обычно люди прибегают к внушению, когда они боятся сказать это прямо. Вместо того, чтобы говорить «приложение должно работать на Android 3.x и выше», они говорят «я бы предложил сделать приложение совместимым с Android 3.x и выше». Увидеть разницу? Во втором предложении автор пытается избежать личной ответственности. Он не говорит «точно Android 3.x»; Он просто предлагает. Не будь трусом; Скажи прямо. Если вы ошибетесь, мы исправим вас.

И, конечно, мнения не оцениваются вообще. Это не письмо другу; Это официальный документ, принадлежащий проекту. Через несколько месяцев или недель вы можете покинуть проект, а кто-то другой будет работать с вашим документом. Спецификация - это контракт между спонсором проекта и командой проекта. Мнение автора документа здесь не имеет значения. Вместо того, чтобы замечать «кажется, что Java будет быстрее» и предлагая «мы должны ее использовать», скажем, «Java работает быстрее, поэтому мы должны ее использовать». Очевидно, вы положили его туда, потому что так думали. Но как только он появился, нам все равно, кто он, и что вы думаете об этой проблеме. Эта информация просто смущает нас больше, поэтому пропустите ее. Просто факты, нет мнений.

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

Необходимо поддерживать несколько версий API. Как именно это делать не имеет большого значения.

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

Но опять же, позвольте мне повторить: спецификация не является дискуссионной площадкой.

Смешивание функциональных и качественных требований

Пользователь должен плавно и быстро прокручивать список изображений в профиле.

Это типичная ошибка почти в каждой спецификации, которую я видел. Здесь мы смешиваем функциональное требование («прокручивать изображения») и и нефункциональное («прокрутка плавная и быстрая»). Почему это плохо? Ну, нет конкретной причины, но она проявляет недостаток дисциплины.

Такое требование трудно проверить или проверить, его трудно отследить и его трудно реализовать. Будучи программистом, я не знаю, что важнее: прокручивать или прокручивать быстро.

Кроме того, трудно изменить такое заявление. Если завтра мы добавим еще одно функциональное требование - например, прокрутку списка друзей - мы хотим, чтобы эта прокрутка также была гладкой и быстрой. Затем, через несколько дней, мы хотим сказать, что «быстрое» означает менее 10 миллисекунд времени реакции. Затем мы должны дублировать эту информацию в двух местах. Посмотрите, насколько бесполезным может стать наш документ?

Таким образом, я настоятельно рекомендую вам всегда документировать функциональные и нефункциональные требования отдельно.

Требования к смешиванию и дополнительные документы
Это похоже на предыдущую проблему и может выглядеть так:

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

Очевидно, что в этом параграфе описаны две вещи. Во-первых, пользователь может скачать отчет в формате PDF. Во-вторых, как должен выглядеть этот отчет. Первое - это функциональное требование, а второе должно быть описано в дополнительном документе (или приложении).

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

Неизмеряемые требования к качеству

Номера кредитных карт должны быть зашифрованы. Приложение должно запуститься менее чем за 2 секунды. Каждая веб-страница должна открываться менее чем за 500 миллисекунд. Пользовательский интерфейс должен быть отзывчивым.

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

Да, это сложно. В основном потому, что есть много факторов. Возьмите эту строку, например: «Приложение должно запускаться через 2 секунды». На каком оборудовании? С каким количеством данных в профиле пользователя? Что означает «запуск»; Это включает время загрузки профиля? Что делать, если возникают проблемы с запуском? Они считают? Таких вопросов много.

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

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

Инструкции по внедрению

Этот пример иллюстрирует очень распространенную ловушку:

Пользователь аутентифицируется через кнопку входа в Facebook и мы сохраняем имя пользователя, аватар и электронную почту в базе данных.

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

Я так не думаю. Только в очень редких случаях это будет иметь значение. В большинстве случаев это просто микроуправление.

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

Вы не должны говорить мне, как реализовать желаемую функциональность

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

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

Дело в том, что я ничего не имею против требований, но я категорически против инструкций по внедрению.

Отсутствие творческой перспективы

Текст может выглядеть так:

При необходимости создается отчет в формате PDF.  С возможностью загрузить его или сохранить в учетной записи.

Проблема здесь в том, что нет никакого «творчества». Эта функциональность более или менее ясна, но непонятно, кто все это делает. Где пользователь? Это просто история о том, что где-то происходит. Это не совсем то, что нужно программистам для его реализации.

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

Пользователю необязательно быть человеком. Это может быть система, клиент API RESTful, база данных, что угодно. Но всегда кто-то. «Возможно скачать ...» не является пользовательской историей. Если существует возможность, то для кого?

Шум

Нашей главной задачей является производительность и привлекательность пользовательского интерфейса.

Это шум(вода). Как читатель этого документа, я не инвестор и не пользователь. Я программист. Меня не волнует, какая ваша «главная забота» в этом проекте. Моя задача - реализовать продукт так, чтобы он соответствовал спецификациям. Если производительность является вашей основной задачей, создайте для меня измеримые и тестируемые требования. И я проверю чтобы продукт удовлетворял им. Если вы не можете создать требование, не пишите мне эту нерелевантную информацию.

Хорошие программисты должны понять, что означает хорошая производительность, верно?

Я не хочу делиться своими проблемами, вашими убеждениями или вашими намерениями. Дело ваше. И вам платят, чтобы правильно и недвусмысленно перевести все это в проверяемые и измеримые требования. Если вы не можете это сделать, это ваша проблема и ваша вина. Не пытайтесь сделать их моими.

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

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

Нет! Не делай этого. Правильно выполняйте свою работу, и пусть программисты делают свою работу.

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

Будет работать, работать, работать

Это еще одна очень типичная ошибка:

API будет поддерживать JSON и XML. Оба формата должны полностью поддерживать все элементы данных. XML необходимо проверять схемой XSD.

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

API поддерживает JSON и XML. Оба формата полностью поддерживают все элементы данных. XML проверен по схеме XSD.

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