Разметка кода
Свой код я размечаю по разделам:
- Функциональные возможности
- Обработчики событий
- Служебные операции
Внутри раздела могут быть как области кода, объединённые директивами #Область / #КонецОбласти, так и отдельные процедуры / функции.
Пример 1:
Пример 2:
Пример 3:
Выглядит наглядно: можно бегло оценить код.
Автогенерация веб-страницы документации кода
Но я решил пойти дальше и написал обработку, генерирующую веб-страницу документации для кода.
Состав страницы:
- Функциональные возможности: диаграмма прецедентов UML, собранная из раздела кода "ФУНКЦИОНАЛЬНЫЕ ВОЗМОЖНОСТИ"
- Программный интерфейс: диаграмма классов UML, автоматически собираемая из всех операций кода. Операции группируются по разделам ("ФУНКЦИОНАЛЬНЫЕ ВОЗМОЖНОСТИ" / "ОБРАБОТЧИКИ СОБЫТИЙ" / "СЛУЖЕБНЫЕ ОПЕРАЦИИ") и областям кода (обрамление метками #Область / #КонецОбласти);
- Далее следуют разделы описания функциональных возможностей. Для каждой функциональной возможности заполняются:
- Последовательность вызова кода: автоматически генерируемая диаграмма последовательности UML для операций, относящихся к данной функциональной возможности. Если в операциях есть комментарии, они также попадут на диаграмму.
- Описание операций кода: таблица с колонками "операция" и "назначение". Назначение операции автоматически описывается нейросетью. При отсутствии подключения к нейросети назначение остаётся пустым.
- После описания функциональных возможностей идёт описание операций кода разделов "ОБРАБОТЧИКИ СОБЫТИЙ" и "СЛУЖЕБНЫЕ ОПЕРАЦИИ". Структура таблицы такая же, как в описании операций кода функциональной возможности.
Пример страницы автодокументации
Функциональные возможности
Программный интерфейс
Функциональная возможность "Формирование документации"
Последовательность вызова кода
Описание операций кода
| Операция | Назначение |
| СформироватьДокументацию() | Назначение данного кода на языке 1С: * Вызов функции СформироватьДокументациюНаСервере для получения исходных данных или структуры документации в формате Markdown.* Вызов функции MarkdownКлиент.СформироватьHTML, которая преобразует полученные данные в формат HTML, пригодный для отображения в интерфейсе.* Переключение активной страницы формы на страницу предварительного просмотра ( СтраницаПросмотр) для демонстрации пользователю сгенерированного HTML-содержимого. |
| СформироватьДокументациюНаСервере() | * Анализ исходного кода на 1С для поиска специальных разделов, помеченных комментариями. * Автоматическая генерация документации на основе найденных областей кода. * Создание PlantUML-диаграмм прецедентов (use case) для отображения функциональных возможностей. * Формирование диаграмм классов для визуализации программного интерфейса. * Генерация диаграмм последовательности для отдельных операций. * Автоматическое создание таблиц с описанием операций и соответствующих им алгоритмов. * Организация и структурирование собранной информации в текстовый документ для дальнейшего использования (например, в качестве веб-страницы или документации). |
| СформироватьДиаграммуПоследовательности() | * Формирование исходного кода для PlantUML-диаграммы последовательности. * Инициализация структуры данных для представления функциональных операций и связей между ними. * Анализ вызовов методов в коде для определения последовательности взаимодействий. * Выявление точек входа, с которых начинается выполнение бизнес-логики. * Построение связей между пользователем и программным кодом на диаграмме. * Рекурсивное описание вложенных вызовов операций для визуализации детального процесса. * Форматирование выходных данных в соответствии с синтаксисом @startuml и @enduml. |
| ДобавитьПереносыСтрокВСлишкомДлинныеНаименования() | Назначение представленного кода на языке 1С: * Функция принимает строку (наименование) и разбивает её на несколько строк, если длина общего текста превышает заданное количество символов. * Основная цель — обеспечить автоматический перенос длинных наименований на новую строку для удобства отображения, например, в печатных формах или интерфейсе. * Алгоритм разбивает исходную строку на отдельные слова, используя пробел как разделитель. * В процессе обработки происходит подсчет длины накопленной строки. * Если добавление следующего слова превышает установленный лимит символов (по умолчанию 30), функция вставляет символ переноса строки. * Если лимит не превышен, слова объединяются в одну строку через пробел. * На выходе функция возвращает преобразованную строку, содержащую символы переноса в тех местах, где длина сегмента текста превысила заданный порог. |
| ОписатьОперациюДиаграммыПоследовательности() | * Генерация кода диаграммы последовательности (вероятно, в формате PlantUML) на основе программного кода 1С. * Поиск и анализ взаимосвязей между методами (вызываемые операции) внутри исходного кода. * Рекурсивное построение иерархии вызовов для отображения на диаграмме. * Обработка комментариев в коде (строки, начинающиеся с //) для их отображения в виде примечаний (note) на диаграмме. * Форматирование длинных строк с именами методов или примечаний для корректного отображения внутри блоков диаграммы. * Использование регулярных выражений для поиска вызовов методов внутри текста программы. * Управление отображением активации объектов на диаграмме с помощью команд активации и деактивации (activate/deactivate). |
| ПолучитьОписаниеОперации() | * Функция объявляется с именем ПолучитьОписаниеОперации и принимает на вход параметр Операция. * В коде предусмотрен закомментированный блок отладки, который позволяет принудительно вернуть пустую строку. * Основная логика заключается в обращении к внешней интеграции ИнтеграцияAITunnel для отправки запроса в нейросеть. * В нейросеть передается промпт с инструкцией описать алгоритм работы кода маркированным списком простого текста, а также поле Код из входящего объекта Операция. * Полученный от нейросети ответ подвергается обработке: символы переноса строки (Символы.ПС) заменяются на тег HTML-разметки , чтобы сохранить форматирование при выводе. * Обработанная строка с описанием возвращается в качестве результата выполнения функции. |
| ПолучитьОбласти() | * Функция предназначена для парсинга входного текста и поиска в нем выделенных блоков, ограниченных метками #Область и #КонецОбласти. * С помощью регулярного выражения функция извлекает наименование области и ее внутреннее содержимое. * Найденные области преобразуются в структуры, содержащие имя области и список операций, полученных через вызов сторонней функции ПолучитьОперации. * Обработанные блоки удаляются из исходного текста, чтобы продолжить поиск следующих вхождений в цикле. * После завершения цикла функция проверяет наличие оставшихся операций за пределами блоков и добавляет их в итоговый массив в виде отдельной структуры с пустым наименованием. * На выходе функция возвращает массив, состоящий из всех найденных структур областей с их операциями. |
| ПолучитьОперации() | * Функция предназначена для поиска и извлечения объявлений процедур и функций из переданного текста. * Инициализируется пустой массив для хранения результатов поиска. * Используется регулярное выражение для идентификации ключевых слов "Процедура" или "Функция", поиска их имен и содержимого параметров вплоть до ключевого слова "КонецПроцедуры". |
ОБРАБОТЧИКИ СОБЫТИЙ
| Операция | Назначение |
| ПриСозданииНаСервере() | Данный фрагмент кода на языке 1С выполняет следующие действия при открытии формы: * Устанавливает активной вкладку «СтраницаКод» в элементе управления «Страницы», чтобы при открытии формы пользователь сразу видел эту страницу. * Вызывает процедуру «ИнициализироватьРендерHTMLИзMarkdown()», которая, вероятно, подготавливает инструменты для преобразования или отображения Markdown-разметки в формате HTML. |
СЛУЖЕБНЫЕ ОПЕРАЦИИ
| Операция | Назначение |
| ИнициализироватьРендерHTMLИзMarkdown() | * Данная процедура под названием "ИнициализироватьРендерHTMLИзMarkdown" служит для подготовки среды отображения контента. * Код выполняет инициализацию переменной "ДокументHTML", вызывая для этого специальный метод "ПодготовитьПолеПромежуточногоHTML" из общего модуля "MarkdownСервер". * Основное назначение этого фрагмента — настроить поле, которое в дальнейшем будет использоваться для конвертации или отображения Markdown-разметки в формате HTML. |
Используемая модель нейросети и цена вопроса
В качестве модели нейросети я использую "gemini-3.1-flash-lite-preview". Она недорогая. Генерация веб-страницы выше обошлась менее, чем в рубль. Но в то же время "gemini-3.1-flash-lite-preview" выдаёт качественные ответы.
Для обращения к нейросети я использую агрегатора aitunnel.ru. Нейросети от Google (gemini), как и многие другие, официально не предоставляются в России. Обратиться к ним можно только через посредников-агрегаторов нейросетей.
Версия платформы
Тестировалось на версии платформы 1С 8.3.27.1936.
Вступайте в нашу телеграмм-группу Инфостарт
