XML-документация — Стандарты A1sCode

📌 Основа

Три маркера A1sCode

Визуальные символы для быстрого чтения документации

Foundation

Система маркеров

Каждый публичный метод должен иметь XML-документацию с тремя маркерами. Они появляются в подсказках IDE и помогают мгновенно понять назначение функции.

Маркер	Тег	Назначение	Обязательно
✦	`<summary>`	Описание функции	✓ Да
➤	`<param>`	Описание параметра	✓ Если есть
⬅	`<returns>`	Возвращаемое значение	✓ Если функция

✦

Summary

Описание

Первая строка — самая важная. Одно предложение, начинается с глагола, заканчивается точкой и маркером ✦

➤

Params

Параметры

Каждый параметр на отдельной строке с указанием типа и описания. Формат: ➤ Имя - Тип: Описание.

⬅

Returns

Возврат

Что функция возвращает. Для процедур этот раздел не нужен. Можно указать несколько вариантов возврата.

📝 Шаблон

Копируй и заполняй

Базовая структура XML-документации

Template

Базовый шаблон

Наведите, чтобы развернуть полный шаблон:

// Краткое описание функции (одно предложение). ✦ // // Параметры: // ➤ Параметр1 - Тип: Описание параметра. // ➤ Параметр2 - Тип: Описание параметра. // // Возвращает: // ⬅ Тип - Описание возвращаемого значения. // // Пример: // Результат = МояФункция(10, "Тест"); Функция МояФункция(Параметр1, Параметр2) Экспорт ib = "Намерение функции"; //✍ // ... код ... КонецФункции

When

Когда писать?

Обязательно: Все функции/процедуры с ключевым словом Экспорт.

Рекомендуется: Сложные внутренние функции, которые могут вызвать вопросы.

Structure

Порядок секций

Секции идут строго в определённом порядке для единообразия:

1. Summary (описание) ✦ 2. Параметры: ➤ 3. Возвращает: ⬅ 4. Пример: // код

✦ Summary

Краткое описание

Первая строка — самая важная

Rules

Правила написания

• Одно предложение — максимум 80 символов
• Начинается с глагола — Создаёт, Возвращает, Фильтрует
• Заканчивается точкой и ✦
• Без технических деталей — только суть
• На русском языке

Comparison

Плохо vs Хорошо

❌ Плохо

// Эта функция принимает массив и // фильтрует его по условию, // используя внутренний алгоритм. ✦

✅ Хорошо

// Фильтрует массив по условию. ✦

Verbs

Глаголы для начала

Создание: Создаёт, Формирует, Генерирует
Получение: Возвращает, Получает, Извлекает
Преобразование: Преобразует, Конвертирует, Переводит
Действие: Фильтрует, Сортирует, Удаляет

Length

Длина строки

Идеально: 40-60 символов
Максимум: 80 символов

Если не помещается — упрощай формулировку, не переноси на вторую строку.

➤ Params

Параметры функции

Каждый параметр — на отдельной строке

Format

Формат записи

Строгий формат для единообразия:

// Параметры: // ➤ ИмяПараметра - Тип: Описание параметра.

Отступ: 2 пробела перед ➤
Разделитель: " - " (пробел-дефис-пробел)
Тип: После имени, до двоеточия

Types

Таблица типов

Тип	Описание
`Строка`	Строковое значение
`Число`	Целое или дробное
`Булево`	Истина/Ложь
`Дата`	Дата и время
`Массив`	Массив значений
`Структура`	Структура с ключами
`ТаблицаЗначений`	Таблица значений
`Произвольный`	Любой тип

Special Cases

Специальные случаи

Необязательные параметры — добавь строку с отступом:

// ➤ Лимит - Число: Максимум записей. // Необязательный. По умолчанию: 100.

Несколько типов — перечисли через запятую:

// ➤ Условие - Строка, Структура: // Фильтр или выражение.

Example

Пример с несколькими параметрами

// Параметры: // ➤ Массив - Массив: Исходный массив для фильтрации. // ➤ Условие - Строка: Выражение фильтра (v > 10). // ➤ ПоУмолчанию - Произвольный: Значение при пустом результате. // Необязательный. По умолчанию: Неопределено.

⬅ Returns

Возвращаемое значение

Что функция отдаёт наружу

Simple

Простой возврат

Один тип — одна строка:

// Возвращает: // ⬅ Массив - Отфильтрованный массив.

Multiple

Несколько вариантов возврата

Когда функция может вернуть разные типы:

// Возвращает: // ⬅ Структура - Найденная строка как структура. // ⬅ Неопределено - Если ничего не найдено.

Procedure

Процедуры

Если это Процедура (не Функция), раздел "Возвращает" не нужен.

// Записывает данные в файл. ✦ // // Параметры: // ➤ Путь - Строка: Путь к файлу. Процедура ЗаписатьВФайл(Путь)

Detailed

Детализация структуры возврата

Для сложных возвращаемых значений описывай поля:

// Возвращает: // ⬅ Соответствие - Группировка по типам. // Ключ: Тип (например, Тип("Число")). // Значение: Массив элементов этого типа.

💡 Примеры

Как писать примеры

Покажи, как использовать функцию

Rules

Правила примеров

• Реальный use-case — не абстрактные данные
• Рабочий код — можно скопировать и запустить
• Комментарий результата — что будет после выполнения
• Минимум кода — только суть, без лишнего

// Пример: // МассивЧисел = A1sAR.Of(1, 2, 3, 4, 5); // Результат = A1sAR.Filter(МассивЧисел, "v > 2"); // // Результат: [3, 4, 5]

Full Example

Полный пример документации

Идеальная документация функции (наведите для раскрытия):

// Группирует элементы массива по типу данных. ✦ // Возвращает Соответствие, где ключ — тип, значение — массив. // // Параметры: // ➤ ВходящийМассив - Массив: Массив с элементами разных типов. // // Возвращает: // ⬅ Соответствие - Группировка по типам. // Ключ: Тип (например, Тип("Число")). // Значение: Массив элементов этого типа. // // Пример: // Смешанный = A1sAR.Of(1, "Текст", 2, "Ещё", Истина); // ПоТипам = A1sAR.GroupByType(Смешанный); // // // ПоТипам[Тип("Число")] -> [1, 2] // // ПоТипам[Тип("Строка")] -> ["Текст", "Ещё"] // // ПоТипам[Тип("Булево")] -> [Истина] Функция GroupByType(Знач ВходящийМассив) Экспорт ib = "Распределяем элементы по корзинам типов"; //✍ Результат = Новый Соответствие; //✏ Для Каждого Элемент Из ВходящийМассив Цикл //⟳ ТипЭлемента = ТипЗнч(Элемент); //✏ Корзина = Результат.Получить(ТипЭлемента); //⚡ Если Корзина = Неопределено Тогда Корзина = Новый Массив; //✏ Результат.Вставить(ТипЭлемента, Корзина); //✏ КонецЕсли; Корзина.Добавить(Элемент); //✏ КонецЦикла; Возврат Результат; //↩ КонецФункции

Mistakes

Типичные ошибки

❌ Абстрактные переменные (a, b)
❌ Нерабочий код
❌ Отсутствие комментария результата
❌ Слишком длинный пример
❌ Пример не показывает основное применение

Multiple

Несколько примеров

Для сложных функций можно добавить несколько примеров с разными сценариями использования.

// Пример 1 (простой): // ... // // Пример 2 (с фильтром): // ...

✅ Чек-лист

Проверь перед коммитом

Состояние сохраняется в браузере

← Назад

Все стандарты

Вернуться к списку стандартов A1sCode

Перейти →

Следующий →

Intention Block

Блоки намерения — ib = "..." в начале функции