Знаете, как часто бывает: читаешь чей-нибудь умный труд (например, прекрасную книгу Карла Вигерса «Разработка требований к программному обеспечению»), всё вроде понятно — требования должны быть полными, корректными, осуществимыми… Теория отличная, хорошо описаны процессы, связанные с коммуникациями с заказчиком (как проводить интервью, какие бывают требования к информационной системе и как их выявлять).
Но вот чего действительно не хватает, так это живых примеров технических спецификаций, которые можно было бы использовать в работе. Именно это я и искал, когда изучал книгу Вигерса и другие материалы. Не нашел и поэтому решил описать свой личный опыт. Ведь когда я начинал свою трудовую деятельность аналитика, то допускал довольно много критичных ошибок, которые выявлялись как на этапе разработки, так и в ходе сопровождения системы. Сегодня я хочу поделиться этими уроками жизни. Расскажу о реальных кейсах и покажу, как избежать типичных ошибок в документации. Хочу верить, что эта информация пригодится как начинающим аналитикам, так и профи, например, для создания чек-листов при проверке требований.
Постановка от заказчика
Для наглядности возьмем знакомый многим пример — систему закупок химических препаратов, как в исследовании Карла Вигерса. Что ж, начнем сразу с конкретики.
Представьте себе, что заказчик попросил добавить в систему возможность, чтобы ее администратор мог выдать разрешение на сотрудника организации по закупке препаратов. В разрешении должна быть указана дата, до которой оно действует, сведения о человеке, кому оно выдано, включая паспортные данные (обязательно по внутреннему регламенту компании) и размеры средств, по которым можно делать закупки. Дополнительно для статистики нужно сохранить условно возможное количество закупаемых препаратов.
Давайте посмотрим на пример типичной спецификации.
Таблица 1. Пример спецификации
Название сценария | Выдача разрешения на закупку химикатов | ||
Предусловие | Пользователь который выдает разрешение, обладает полномочиями администратора. Пользователь, которому выдается разрешение, не обладает действующим разрешением | ||
Инициирующее событие | Администратор системы в контекстом меню активировал кнопку “выдать разрешение” для сотрудника организации | ||
Результат | Выдано разрешение на закупку химикатов | ||
Сценарий выдачи разрешения | |||
N | Действие | Экранная форма | Сообщение пользователю |
1. | Администратор системы в контекстом меню активировал кнопку “выдать разрешение” для сотрудника организации | Экранная форма выдачи разрешения | |
2. | Администратор заполняет сведения в форме и активирует кнопку “Выдать разрешение” | Модальное окно уведомления | Разрешение успешно выдано |
3. | В Базе данных сохранить значение условного количества закупаемых препаратов (“Максимальная цена контракта”/”Максимальная цена единицы товара”) | ||
Форма выдачи разрешения
Таблица 2. Описание формы выдачи разрешений
Название элемента | Тип элемента | Правила функционирования |
Фамилия, имя, отчество | Текстовое поле | Обязательное для заполнения поле |
Серия и номер паспорта | Текстовое поле | Обязательное для заполнения поле |
Срок действия разрешения | Дата | Обязательное для заполнения поле. Можно указать дату больше или равной текущей |
Максимальная цена единицы товара | Числовое поле | Обязательное для заполнения поле. Можно указать число строго больше 0 |
Максимальная цена контракта | Числовое поле | Обязательное для заполнения поле. Можно указать число строго больше 0 |
Выдать разрешение | Кнопка | Кнопка доступна, только если заполнены все обязательные поля |
Сколько вы насчитали здесь ошибок?
Давайте же приступим к их разбору. Предупрежу, что порядок ошибок здесь произвольный и не претендует на иерархию. Рассмотрим все последовательно.
Ошибка 1. Не приведены источники требования
В поле «Серия и номер паспорта» формы выдачи разрешения не указан источник требования, хотя данное поле обязательно, согласно внутреннему регламенту.
Технически это ограничение можно не указывать, ошибки при разработке не будет. Однако если не указать, то будут сложности при сопровождении системы. Например, спустя время, может произойти инцидент, при котором разрешение нужно выдать человеку, у которого нет паспорта, а есть только свидетельство о рождении.
Если заранее в спецификации не указать ссылку на внутренний регламент, то можно в будущем или после смены команды и забыть про его существование и добавить возможность указывать сведения без паспортных данных. Это, безусловно, будет уже ошибкой. Чтобы такого не случилось, было бы неплохо обсудить вероятность заранее при написании требований.
Ошибка 2. Не указаны ограничения на экранных формах о количестве символов
Обратите внимание, что в требованиях к экранной форме не указано, сколько символов можно добавить в полях формы. К каким ошибкам может это привести? Предположим, к тому, что пользователи начнут вводить ФИО длиной в 200 символов (утрирую), при том, что в базе данных (БД) установлен предел до 100 символов. И система просто упадет.
Повторюсь, что ставить ограничение на формах при вводе необходимо, чтобы нельзя было указать символов больше, чем хранимое значение в БД или, в зависимости от бизнес-требований, еще больше сократить эту возможность. Вряд ли все-таки у человека будет ФИО длиною более 2000 символов, но можно вполне поставить такое ограничение.
Ошибка 3. Не описан контроль после размещения сведений. Указаны проверки только по предусловию
Теперь представьте, что от заказчика было требование, чтобы только администратор системы мог выдавать разрешения и вы добавили это условие проверки только при запуске функции.
Далее, вы все проверили, и у конкретного исполнителя-администратора есть полномочия. Все в порядке. Но пока этот администратор оформлял разрешение на экранной форме, руководитель организации мог снять с него данное полномочие. Получается, что пользователь, утративший полномочия администратора, но успевший до этого перейти к работе с формой, все же выдаст разрешение, уже не имея на это прав.
Здесь советую остановиться и переварить прочитанное. Потому что перед вами одна из самых часто встречающихся ошибок, с которой я сталкивался в работе и которая может привести к серьезным инцидентам. На анализ того, почему пользователь без полномочий администратора смог выдать разрешение, поверьте мне, уйдет масса времени. Потому что догадаться, что сработал именно этот сценарий и воспроизвести его поэтапно, крайне непросто.
То же касается и ситуации с тем, что у того, кто получает разрешение, может быть только одно действующее. А что если, пока один администратор выдавал сотруднику разрешение и вводил сведения, параллельно уже другой назначенный администратор успел выдать ему другое разрешение. Тогда в системе будет два разрешения с разными датами и суммами. Что с этим делать? Чтобы избежать проблем, при выдаче разрешения нужно также проверять условия, которые были при запуске функции.
Ошибка 4. Не учтен часовой пояс при указании срока действия
Обратите внимание, что в нашем примере у срока действия разрешения не указан часовой пояс, есть только дата. А теперь внимание - вопрос!
Если, к примеру, разрешение было выдано до 01.01.2030 г. и в Москве сейчас 23:00, но пользователь делает закупку в Екатеринбурге, где уже 01:00, 02.01.2030 г. Получается, что он выполнил закупку после истечения разрешения? Или все-таки нет?
Вопрос открытый и такая ситуация может привести к серьезным ошибкам. Поэтому, если вы указываете дату и время, никогда не забывайте внести также сведения о часовом поясе.
Ошибка 5. Не покрыт весь диапазон возможных значений реквизитов
В сценарии написано, что нужно сохранить такое значение условного количества закупаемых препаратов как «Максимальная цена контракта»/»Максимальная цена единицы товара». Автор спецификации даже подстраховался и указал, что для поля «Максимальная цена единицы товара» нельзя на форме указать значение «0». Но, как часто бывает, далее могут быть проблемы с сопровождением.
В дальнейшем в ходе жизни проекта могут убрать ограничение, что параметр не может быть равен нулю. Поверьте, никто потом и не вспомнит, что он где-то там используется в формуле и на ноль делить нельзя. Также сведения о разрешении могут сразу поступить из другой системы по интеграции, где могла не проводиться проверка на равенство нулю. И в системе будет ошибка.
Также в БД есть ограничение на максимально возможное хранимое число. При этом на экранной форме нет никаких указаний для размера вводимых значений. Если в числителе будет большое значение, а в знаменателе - близкое к нулю (0.00…1), тогда полученное значение будет слишком большим, чтобы его сохранить, и система выдаст ошибку.
Ошибка 6. Не указаны коды элементов на экранной форме
В примере спецификации у элементов на экранной форме нет кодов и в описании таблицы тоже нет кода элемента. Команде разработки и тестирования на форме нужно будет искать элемент визуально только по названию, что неудобно. Также в ходе жизни проекта очень часто названия элементов меняются и на форме дизайнеры их могут не поменять, а в тексте требований значения будут исправлены и сделать соответствие уже будет невозможно.
Даже простая нумерация элементов на экранной форме сильно облегчает восприятие.
Экранная форма выдачи разрешения
Ошибка 7. Нет указания, как элемент на форме называется в БД
Помимо указания кодов элементов на экранной форме, также было бы удобно написать в таблице, как называются определенные параметры в БД. Указать название таблицы и столбец, где они будут храниться. Это будет удобно и разработке, и сопровождению для написания скриптов, если какие-то данные нужно будет поменять.
Ошибка 8. Не приведены нефункциональные требования
После выдачи разрешения, нужно произвести проверки, как мы обсудили ранее (что у пользователя есть полномочия администратора; что у того, кому выдают разрешение, нет других — действующих). Такой аудит может занимать продолжительное время. И тогда возникает ряд вопросов.
Что же в этот период будет видеть пользователь?
Если процесс будет длиться долго, то может добавить подсказку для пользователя или установить требование, чтобы проверка занимала не более пяти секунд?
А если сервис для проверки пользователя на предмет полномочий администратора вообще недоступен, то сколько ждать ответа?
Что делать, если ответ вообще не поступит?
Для корректного поведения системы нужно также описать все эти требования.
Ошибка 9. Не указано, когда и в какой момент сохраняются данные
Давайте подумаем, в чем может таиться опасность, если заранее не описано, в какой момент и когда сохраняются сведения.
Что будет, если пользователь введет часть данных и закроет вкладку браузера, где вводил сведения?
Когда пользователь после этого вернется на форму выдачи разрешения, ранее введенные данные отобразятся или нет?
Что произойдет, если сведения сразу сохранять до размещения по факту их указания в полях, а пользователь закроет вкладку и больше не вернется?
Что делать с проектом: хранить его вечно или когда-то удалить?
Вот некоторый список вопросов, которые легко перерастают в крупные проблемы. Чтобы их избежать, нужно заранее продумать сценарии и ответы.
Ошибка 10. Не учтены все альтернативные сценарии
В базовом сценарии написано, что пользователь является администратором, и он начинает процесс выдачи разрешения. Вот ключевые вопросы, которые стоит себе задать.
А что будет если у пользователя нет данных полномочий?
Он получит какое-то уведомление, что у него нет полномочий, или система просто выдаст сообщение об ошибке?
Чтобы найти ответы прежде, чем возникнут неприятности, нужно описать все альтернативные сценарии и то, когда они возникают.
Вывод
В завершение хочу подчеркнуть, что идеальных требований не существует. При их описании всегда приходится искать баланс между детальностью спецификации и скоростью разработки. Конечно, вы не можете учесть абсолютно все сценарии. Но мой совет в том, чтобы оценивать уровень риска для проекта и описывать требования соответственно.
Если вы новичок, то лучше перестраховаться и прописать деталей больше, чем меньше. Со временем с собственным багажом ошибок и достижений вы научитесь чувствовать тот оптимальный уровень детализации, который обеспечит эффективное взаимодействие с командой разработки.
Надеюсь, что мои жизненные примеры были полезны и опытным коллегам. Буду рад, если в комментариях вы дополните информацию своими наблюдениями.
*Статья написана в рамках ХабраЧелленджа 3.0, который прошел в ЛАНИТ осенью 2024 года. О том, что такое ХабраЧеллендж, читайте здесь.