Каждый разработчик 1С рано или поздно сталкивается с ситуацией, когда приходится возвращаться к собственному коду двухлетней давности или разбираться в огромном массиве недокументированных доработок, доставшихся в наследство от предыдущего программиста. В такие моменты становится очевидно, что отсутствие системы документирования — это огромный технический долг, который замедляет разработку, усложняет обновление конфигураций и приводит к хаосу при поддержке пользователей.
В этой статье мы подробно разберем, как выстроить эффективную систему документирования изменений в 1С, начиная от простейших комментариев в коде и заканчивая современными инструментами автодокументирования, ведения баз знаний и автоматического тестирования.
Прежде чем приступать к написанию внешних текстовых инструкций, мы должны навести порядок внутри самой информационной базы. Если наши доработки хаотично разбросаны по всей типовой конфигурации, разобраться в них будет чрезвычайно трудно. Разберем основные правила хорошего тона при создании новых объектов метаданных:
_ИмяПроекта_ или _Заказчик_). Это позволяет мгновенно визуально отделить доработки от типового функционала фирмы "1С" при сравнении и объединении конфигураций.Комментарии в коде — это базовый уровень документирования, но они приносят пользу только тогда, когда написаны по определенному стандарту. Фирма "1С" разработала строгие требования к оформлению процедур и функций. Если мы оформляем комментарии по этим правилам, сторонние инструменты смогут автоматически собирать из них полноценные технические руководства.
Проанализируем правильный шаблон комментирования экспортных методов в общем модуле:
// Выполняет расчет стоимости товаров по заданным параметрам с учетом персональных скидок.
//
// Параметры:
// ДокументСсылка - ДокументСсылка.РеализацияТоваровУслуг - Ссылка на рассчитываемый документ продажи.
// Отказ - Булево - Признак отказа от проведения документа в случае критических ошибок расчета.
//
// Возвращаемое значение:
// Структура - Результаты произведенного расчета:
// * СуммаДокумента - Число - Общая сумма с учетом предоставленных скидок.
// * СуммаНДС - Число - Сумма рассчитанного налога на добавленную стоимость.
//
Процедура РассчитатьСтоимостьТоваров(ДокументСсылка, Отказ) Экспорт
// Выясним причину возможного отказа на предварительном этапе
Если Не ЗначениеЗаполнено(ДокументСсылка) Тогда
Отказ = Истина;
Возврат;
КонецЕсли;
// Основной алгоритм расчета...
КонецПроцедуры
Для не визуальных объектов (например, фоновых заданий, подписок на события) комментарии в модуле менеджера или в начале общего модуля — это единственный способ быстро понять логику их работы без глубокой отладки. Обязательно указывайте взаимосвязь: какие объекты вызывают данный код, какие данные изменяются и в какой последовательности.
В современной практике разработки 1С классическое "Хранилище конфигурации" постепенно уступает место современным инструментам контроля версий. Использование 1C:EDT (Enterprise Development Tools) в связке с репозиторием Git (GitLab, GitHub, Gitea) кардинально меняет подход к ведению документации:
TASK-1204: Добавлен расчет скидки в чеке), чтобы вся история изменений кода автоматически привязалась к описанию бизнес-требований..md файлов. Документация меняется одновременно с кодом в рамках одного коммита, что гарантирует ее актуальность.Традиционные инструкции для пользователей, оформленные в виде файлов Word со стрелочками и скриншотами, имеют огромный минус — они моментально устаревают при изменении интерфейса программы. Чтобы решить эту проблему, рассмотрим передовой подход с использованием методологии BDD (Behavior-Driven Development) и инструмента Vanessa-Automation.
Процесс создания автоинструкций выглядит следующим образом:
Посмотрим на пример простейшего сценария для создания новой реализации:
Функционал: Создание документа продажи услуг
Сценарий: Оформление новой услуги клиенту
Дано Я открываю основное окно программы
И Я перехожу к списку документов "Реализация товаров и услуг"
Когда Я нажимаю кнопку с именем "Создать"
И Я заполняю поле "Клиент" значением "Основной покупатель"
И В табличной части "Товары" я нажимаю кнопку "Добавить"
И Я заполняю колонку "Номенклатура" значением "Услуга по доработке 1С"
И Я заполняю колонку "Количество" значением "1"
И Я заполняю колонку "Цена" значением "5000"
И Я нажимаю кнопку "Провести и закрыть"
Тогда Система проводит документ без вывода предупреждений и ошибок
Для долгосрочного хранения информации о структуре доработанной конфигурации используются специализированные вики-системы и трекеры задач. Разберем наиболее популярные связки инструментов:
Для того чтобы выстроить работающую систему документирования доработок в 1С, не обязательно внедрять сразу все описанные инструменты. Начните с малого и двигайтесь по шагам:
Vanessa-Automation, чтобы автоматизировать процесс генерации актуальных инструкций.Помните, что время, затраченное на качественное описание архитектуры и логики работы доработки сегодня, сэкономит вам и вашей команде недели работы в будущем при разборе нештатных ситуаций или обновлении конфигурации.