Одним из самых важных инструментов, который помогает организовать процесс разработки программного обеспечения, является «Спецификация на разработку», или СНР. Этот документ служит своего рода дорожной картой для всей команды, от аналитиков до разработчиков, и позволяет четко определить требования к продукту. Но что делать, когда на проекте работают десятки аналитиков и каждый пишет спецификацию «в свободной форме»? Ответ прост: использовать шаблоны.
Привет, Хабр! Меня зовут Анатолий Троян, я ведущий разработчик и технический архитектор IBS. В этой статье я хочу поделиться личным опытом применения шаблонов СНР на реальном проекте по разработке 1С-системы: как мы писали спецификации, какие у нас при этом возникали проблемы, почему вообще решили все стандартизировать и как отрабатывали изменения в документе.
Кто в лес, кто по дрова: предпосылки стандартизации
За годы работы в ИТ на разных проектах и в разных компаниях я повидал, наверное, все виды спецификаций. У каждого аналитика свой стиль написания, свой подход, свое «видение». Кто-то пишет спецификацию как пользовательскую инструкцию, кто-то — как описание бизнес-процесса, кто-то рисует бесконечные схемы, а кто-то катает сплошной текст.
Когда над одним проектом работают более 50 аналитиков одновременно и сам проект обрастает сотней разных спецификаций, это создает очевидные сложности для технического архитектора, который должен верифицировать СНР, а также приводит к проблемам со взаимозаменяемостью разработчиков и сдачей спецификации заказчику. Работать без стандартизации документов на проектах таких масштабов — значит годами преодолевать хаос.
Частая проблема, которая возникает при анализе мест использования, например, каких-то добавленных реквизитов или алгоритмов, — это анализ самих объектов конфигурации. Поскольку мы работаем с 1С, у нас есть такие абстракции, как Объект конфигурации, Справочник, Документ и Реквизит. Всегда хочется понять, где тот или иной объект конфигурации используется и в какой спецификации он определен. При написании спецификации в виде простого текста или инструкции все это часто теряется, а потом не ищется стандартным поиском по документу ввиду, опять же, отсутствия стандартизации. Когда спецификаций много и между ними выстраиваются сложные взаимосвязи, их тяжело анализировать, учитывать и особенно вносить изменения в реквизиты и структуру хранения данных.
Кроме того, СНР нередко превращается в смешение частей инструкций, проектных решений, сценариев тестирования и технических требований.
Как единый стандарт помогает в разработке
Приступив к новому большому проекту в компании, мы поняли, что нам необходимы шаблоны и что стандартизировать нужно не только внешний вид, но и содержание спецификаций.
Что мы хотели получить от стандарта:
Строгое и четкое определение типов, алгоритмов и места внесения доработки. Точно выраженная мысль аналитика — гарантия того, что над постановкой предметно думали и мысль будет понята и заказчиком, и разработчиками.
Возможность верифицировать техническое задание до выполнения разработки.
Разделение изменений структуры хранения данных, алгоритмов и пользовательских интерфейсов.
Четкое техническое задание, которое станет залогом быстрой разработки и отсутствия простоев разработчиков.
Лучшую декомпозицию задач для более точного планирования трудозатрат.
Более прогнозируемый результат разработки.
Наличие сценариев тестирования и критериев приемки.
Основные принципы стандарта
Основополагающий принцип стандарта, которым мы руководствовались при его создании, — это максимальное приближение структуры СНР непосредственно к структуре конфигурации. Это наиболее простое решение, которое может доставить сложности только тем аналитикам, которые, возможно, недавно оказались в профессии и ни разу не заходили в конфигуратор. Но даже они должны в общих чертах представлять, из чего состоит конфигурация 1С, как выглядит структура хранения данных и как пользоваться консолью запросов.
От того, насколько качественно мы продумываем структуру хранения данных, зависит, как в целом система будет работать. Это элемент технического проектирования системы, который начинает аналитик, а продолжает тимлид или технический архитектор — он же помогает утвердить финальный вид хранения данных, оптимальный с точки зрения решения задач, производительности и стандартов разработки 1С.
Для примера — кусочек нашей СНР из Confluence:
Как видно на правой схеме, по каждому объекту конфигурации уже определены все ключевые данные, включая имя, синоним (отображение в конфигурации) и нахождение в подсистеме. В поле «Идентификатор объекта метаданных» указана трассировка объектов логической модели из Проектного решения, это помогает сохранить «наследственность» и единообразие структур данных.
Такая структура спецификации сразу разбивает блок работ на отдельные задачи: по сути, каждый заголовок — это и есть задача в Jira. Встроенный в шаблон механизм декомпозиции на задачи облегчает планирование, разработку и контроль статуса находящихся в работе задач. Казалось бы, очевидная вещь. Но в своей практике я встречался и с противоположным подходом, когда в таск-менеджере заводится одна гигантская задача «Выполнить разработку по СНР». Разработчик забирает ее в работу на месяц, и отследить по ней статус невозможно.
Следующий момент, который относится не столько к структуре, сколько к общему подходу к написанию спецификации. Нужно понимать, что этот документ близок к техническому заданию, написанному строго по ГОСТу. На «Инфостарте» есть масса статей-объяснялок, где подробно рассматривается, что же такое техническое задание с опорой на ГОСТ.
Я бы выделил три пункта, или три свойства, которые должны быть у технического задания и, соответственно, у СНР:
Быть понятной. Адресат спецификации — технический специалист, который будет вести по ней разработку. Хорошая спецификация — это документ, из которого разработчик однозначно поймет, что ему нужно делать. При этом в спецификации можно использовать специализированные термины, которые не всегда будут понятны бизнес-пользователю — для него существуют другие документы, такие как Инструкции, Проектные решения и Сценарии тестирования.
Быть конкретной. Нельзя оставлять «белых пятен», формулировок, допускающих двоякое толкование. В спецификациях, составленных бывшими бухгалтерами, нередко встречаются такие обтекаемые фразы: «Получить конечное сальдо по такому-то счету» или, еще более непонятно, «Получить остатки товаров на складах и записать их в таблицу». Здесь должно быть указание конкретного источника данных (регистра) и параметров отбора данных.
Быть тестируемой. В идеале стандарт СНР должен включать не только шаблон, но и некоторый набор стандартных действий, которые выполняет разработчик. К таким действиям «по умолчанию» для новых объектов относятся, например, создание ролей, создание форм, добавление в подсистему и добавление в интерфейс. Требования не должны быть сформулированы таким образом, чтобы их нельзя было проверить. Также у нас должен быть сценарий тестирования и тестовый набор данных.
Еще один важный принцип стандарта — это строгое разделение структуры данных, алгоритмов и внешнего вида форм.
Если мы определяем форму, то отдельно рисуем макет, то есть ее внешний вид. Если на форме выводятся какие-то данные, которые не хранятся в базе данных, то мы используем шаблон для раздела «Реквизиты формы». Также у нас есть алгоритмы формы, которые тоже прописываются в событийной парадигме, в которой в принципе работает 1С. Другими словами, поведение формы важно описывать не простым текстом, а в виде таблицы «Алгоритм заполнения», а также указывать в описании алгоритма, какое событие запускает его выполнение.
Что еще есть в нашем стандарте СНР:
отдельный шаблон для каждого типа объекта;
объект «Функция» для неопределенных ситуаций, когда аналитик не знает, как именно будет реализован тот или иной механизм;
шаблон документа «Спецификация на интеграцию» с мэппингом данных для интеграций.
Типичные проблемы при написании спецификаций
Вот с чем я лично постоянно сталкиваюсь, читая спецификации на разработку:
полное отклонение от принятого стандарта;
соблюдение стандарта по форме, а не по сути;
отсутствие логики и корректного описания алгоритмов;
несоблюдение соглашения о префиксах и суффиксах объектов;
перегрузка СНР лишними данными, например стандартными реквизитами;
ссылки на объекты и реквизиты, которые еще не описаны или должны будут описаны другим блоком;
неточное описание типов, задание строк или чисел без длины.
Изменения в спецификациях
В дополнение к спецификации важно продумать конкретный регламент того, как вносятся и согласуются изменения. Мы приняли решение, что изменения в текст можно вносить до тех пор, пока СНР не верифицировал технический архитектор. После этого все изменения должны быть оформлены через отдельные задачи в Jira, которые у нас помечаются префиксом «ИЗМ_». На эти задачи также создаются задачи на согласование изменений, которые уходят на руководителя разработки.
Важный момент, на котором на практике мы, если честно, нередко спотыкаемся, — это описание исключительно самого изменения относительно первоначальной задачи. Вместо этого многие просто копируют исходную постановку и, если не забывают, выделяют разницу красным цветом. В результате объем спецификации растет, а руководитель разработки вынужден сидеть и сравнивать изменения вручную.
Проблемы стандарта
Использование шаблонов снимает многие проблемы хаотичных спецификаций, о которых я говорил вначале. Но на практике не все получается гладко, и у любой стандартизации есть свои недостатки. Создать такую четкую СНР и прописать все структуры данных — задача не из легких. Даже мне как техническому архитектору бывает трудно с ходу спроектировать некий блок, понять, как он будет технически работать, и описать все регистры. Иногда даже приходится делать прототипы.
Что не так со стандартом спецификаций:
Сложность разработки СНР для аналитиков, особенно если необходимо затрагивать изменения типового функционала, далеко не все понимают логику его работы.
Сложность описания механизмов, которые повторяют типовые, так как стандарт обязывает описать алгоритмы, которые могут быть скрыты от аналитиков.
Загромождение СНР большим количеством изменений.
Большое количество отклонений от стандарта и большие организационные затраты на его поддержание, когда на проекте работает много аналитиков.
Сложные бюрократические процедуры на мелкие изменения.
Оценка результатов использования на реальном проекте
Внедрив на текущем проекте стандарт спецификаций на разработку, я заметил следующее:
Высокая трудоемкость разработки и проверки СНР, соответствующих стандарту по форме и по сути. Проще говоря, чтобы сделать качественную спецификацию, нужно много светлых голов аналитиков, которые будут корпеть над каждой строчкой. Если аналитиков не хватает, это проблема, потому что в погоне за качеством спецификаций мы теряем скорость их написания.
Скорость разработки по качественным СНР гораздо выше среднего. Если вложить силы в написание и согласование, в дальнейшем это позволит сэкономить на разработке. Можно задействовать разработчиков более низкого грейда, их легче вывести на проект, они не простаивают в ожидании разъяснений, да и проблем со сдачей заказчику не бывает.
Больше всего проблем вызвал блок бухгалтерского налогового учета, где, в отличие от оперативных блоков, в принципе сложно описывать доработки в таком формате. Трудозатраты на разработку по этому блоку оказались выше, чем мы ожидали.
Более половины СНР не соответствуют в итоговом виде стандарту или соответствуют частично.
Стандарту не хватает методологического документа, помимо верхнеуровневых шаблонов. Не хватает примеров и шаблонов по заполнению полей шаблона.
И тем не менее главный вывод такой: наличие шаблонов и даже частичное следование стандарту повышает эффективность работы на больших проектах. Да, поначалу аналитики могут быть не в восторге от идеи стандартизации: вместо того чтобы «творить по наитию», они вынуждены заполнять таблицы по шаблону. Но в финале выигрывают все: освоив стандарт, аналитики составляют спецификации быстрее, разработчики четко понимают, что от них требуется, а заказчик получает на руки прозрачную документацию и легче согласует проект.
