Как организовать документирование доработок в 1С: лучшие практики и инструменты

← На главную

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

Метод 1: Гибридный подход «Код + Таск-трекер»

Это самый распространенный и доступный способ для небольших команд. Его суть заключается в неразрывной связи между кодом в конфигурации и задачей в системе учета (например, Jira, Redmine, Asana или даже простая доска в Trello).

Разберем по шагам, как это реализовать:

Фиксация задачи: Каждой доработке присваивается уникальный номер (ID) в таск-трекере. Там описывается постановка задачи, ожидаемый результат и принятое техническое решение.
Комментирование в коде: При внесении изменений в модули программист обрамляет измененный блок комментариями. Важно указывать номер задачи, чтобы можно было быстро найти контекст в трекере.

Пример оформления комментария в коде:


// {ЗАДАЧА_12345} [ИвановИИ] 25.05.2023 ->
// Добавлена проверка на заполнение склада для управленческого учета
Если ЗначениеЗаполнено(Объект.Склад) Тогда
    // Новая логика
КонецЕсли;
// <- {ЗАДАЧА_12345}

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

Метод 2: Использование истории хранилища и меток

Для тех, кто хочет держать код «чистым» от лишних комментариев, идеально подходит использование возможностей Хранилища конфигурации 1С. Рассмотрим, как это работает эффективно:

При помещении объектов в хранилище (Check-in) крайне важно заполнять поле описания. Хорошим тоном считается указывать в первой строке номер задачи, а далее краткое резюме сделанных изменений. Если команда использует поле Метка в хранилище, туда также можно дублировать номер задачи или версию релиза.

Выясним преимущества этого метода:

Код остается читаемым, без визуального мусора.
Через функцию «История объекта» можно сравнить любую версию и увидеть дифф (разницу) именно по конкретной задаче.
Видно, какие именно объекты (справочники, документы, формы) были изменены в рамках одного коммита.

Метод 3: Переход на Git и 1C:EDT (Enterprise Development Tools)

Если проект растет, стоит рассмотреть современные инструменты разработки. Использование Git совместно с 1C:EDT выводит документирование на новый уровень. Рассмотрим основные возможности:

Blame (Аннотирование): В Git можно одной кнопкой посмотреть, кто, когда и в рамках какой задачи изменил конкретную строку кода. Это избавляет от необходимости писать фамилии и даты в комментариях внутри модулей.

Интеграция с GitLab/GitHub: Если в сообщении к коммиту указать номер задачи (например, "ref #502"), современные системы автоматически свяжут этот коммит с карточкой задачи в трекере. Перейдя в задачу, вы увидите список всех измененных файлов и строк кода.

Docs-as-Code (Документация как код): Мы можем хранить файлы технического описания (в формате Markdown) прямо в репозитории с кодом. Это позволяет версионировать документацию вместе с функционалом.

Метод 4: Архитектурные решения (ADR) и логи изменений

Часто программисты забывают не «что» они написали, а «почему» они выбрали именно этот путь. Для этого рекомендуется внедрить практику ADR (Architecture Decision Records). Это короткие текстовые документы, фиксирующие важные решения.

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


## [1.0.5] - 2023-10-12
### Добавлено
- Новый алгоритм расчета скидок в документе "Реализация" (Задача #789).
### Исправлено
- Ошибка округления при распределении транспортных расходов.
### Изменено
- Оптимизирован запрос в обработке "Печать этикеток".

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

Метод 5: Автоматизация и самодокументированный код

Посмотрим на более продвинутые техники, которые минимизируют ручной труд. Проанализируем возможности инструментов автоматизации:

Использование Vanessa-Automation: Если вы пишете автотесты на языке Gherkin, то сами сценарии тестов становятся актуальной пользовательской документацией. Они описывают поведение системы на языке бизнеса.

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

Пример качественного описания функции:


// Рассчитывает остаток товара на указанном складе.
// 
// Параметры:
//  Номенклатура - СправочникСсылка.Номенклатура - Товар, по которому ищем остаток.
//  Склад        - СправочникСсылка.Склады       - Склад хранения.
//  ДатаОстатков - Дата                          - Момент времени для расчета.
//
// Возвращаемое значение:
//  Число - Количество остатка на складе.
//
Функция ПолучитьОстатокТовара(Номенклатура, Склад, ДатаОстатков) Экспорт
    // Реализация...
КонецФункции

Подведение итогов и рекомендации

Выбор метода зависит от масштаба вашего проекта. Для маленькой базы с двумя программистами достаточно сочетания таск-трекера и кратких комментариев в коде с номером задачи. Если же проект подразумевает активное развитие и частые изменения в типовых механизмах, настоятельно рекомендуем рассмотреть связку 1C:EDT + Git.

Важный совет: Какую бы систему вы ни выбрали, главное — дисциплина. Документирование должно стать обязательным этапом задачи (Definition of Done). Без этого любая, даже самая совершенная система, превратится в свалку неактуальной информации.

Рассмотрев все варианты, можно сделать вывод: идеальное документирование — это то, которое встроено в процесс разработки и не требует отвлечения на сторонние инструменты (Word, Excel и прочее). Используйте возможности платформы и современных систем контроля версий для автоматизации этого процесса.