Главная → Стандарты → Intention Block
🟠 Высоко — Рекомендуется для всех функций

💭 Intention Block

Однострочное описание намерения функции. Код говорит, ЧТО он делает. ib говорит, ЗАЧЕМ он это делает.

ib = "Гарантируем уникальность элементов";
💡 Основа

Что такое Intention Block?

Контекст для будущего тебя и для ИИ-ассистентов

Definition

Определение

Intention Block (ib) — это однострочный комментарий в начале тела функции, который описывает намерение, а не реализацию. Переменная ib никогда не используется в коде — это чистый комментарий в форме присваивания.

Функция ДобавитьЭлемент(Массив, Элемент) ib = "Гарантируем уникальность элементов в коллекции"; // ... код ... КонецФункции
Syntax

Синтаксис

Расположение строго определено:

Функция МояФункция(Параметры) Экспорт ib = "Намерение функции"; // ← Сразу после заголовка // Основной код начинается здесь Результат = ... //✏ КонецФункции
🎯 Польза

Зачем нужен ib?

Четыре причины использовать Intention Block

🤖
AI

Для ИИ

Claude/GPT понимают контекст и дают лучшие подсказки. ИИ видит не только код, но и намерение автора.

👀
Review

Для ревью

Ревьюер сразу видит, что хотел автор. Проще найти расхождение между целью и реализацией.

🔮
Future

Для будущего

Через полгода вспомнишь, зачем писал этот код. ib — это записка самому себе в будущее.

🐛
Debug

Для отладки

Если ib не совпадает с поведением кода — баг найден. Либо код неверен, либо ib устарел.

📐 Правила

Четыре правила ib

Как писать хорошие Intention Block

1

Одна строка

Максимум 100 символов. Если не влезает — упрости мысль. Краткость — сестра таланта.

2

Бизнес-язык

Пиши на языке предметной области, не на языке кода. "Применяем скидку клиента", а не "Умножаем на коэффициент".

3

"Зачем", не "Что"

Описывай цель, а не шаги реализации. Код уже говорит, что он делает — ib объясняет, зачем.

4

Глагол в начале

Начинай с действия: Обеспечиваем, Гарантируем, Вычисляем, Проверяем, Избегаем, Фиксируем...

✅ Примеры

Хорошие примеры ib

Вдохновляйся и копируй

Examples

Примеры из реальных проектов

// Функция удаления дубликатов ib = "Исключаем повторы сохраняя порядок оригинала"; // Функция валидации email ib = "Проверяем корректность адреса до отправки письма"; // Функция расчёта скидки ib = "Применяем накопительную скидку постоянного клиента"; // Функция кэширования ib = "Избегаем повторных запросов к БД за один сеанс"; // Функция логирования ib = "Фиксируем действия пользователя для аудита";
Verbs

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

Обеспечиваем — гарантия
Проверяем — валидация
Применяем — трансформация
Избегаем — оптимизация
Фиксируем — логирование
Подготавливаем — инициализация
Собираем — агрегация

❌ Анти-паттерны

Как НЕ надо писать ib

Типичные ошибки и как их избежать

🚫 Anti

Копипаста из Summary

ib должен дополнять XML-doc, а не дублировать его. Summary говорит "Что", ib говорит "Зачем".

🚫 Anti

Технический жаргон

"Итерируем по коллекции" — это не намерение. Пиши на языке бизнеса, а не алгоритмов.

🚫 Anti

Очевидные вещи

"Возвращаем результат" — это и так видно из кода. ib должен добавлять ценность.

🚫 Anti

Многострочность

Если не влезает в строку — упрости мысль. Длинное объяснение = непонятная функция.

Transform

Исправление плохих примеров

❌ Плохо
ib = "Итерируем по массиву и проверяем через Соответствие";
✅ Лучше
ib = "Исключаем дубликаты за линейное время";
❌ Плохо
ib = "Добавляем элемент в конец массива";
✅ Лучше
ib = "Накапливаем результаты для пакетной записи";
⚖️ Сравнение

ib vs XML-doc Summary

Разные инструменты для разных целей

Comparison

Сравнительная таблица

XML-doc Summary ✦ Intention Block (ib)
Где Перед функцией Внутри функции
Для кого Для пользователя API Для разработчика/ревьюера
Отвечает на "Что делает?" "Зачем делает?"
Стиль Формальный Разговорный
Usage

Когда что использовать

XML-doc Summary:
• Описание для IDE и автодополнения
• Документация публичного API
• Формальное описание контракта

Intention Block:
• Объяснение замысла для ревью
• Контекст для ИИ-ассистентов
• Напоминание себе через полгода

← Назад

XML-документация

Маркеры ✦ ➤ ⬅ для документирования функций

Перейти →
Следующий →

SyntaxMarks

Синтаксические метки //✏ //⟳ //⚡ для подсветки кода

Перейти →