Код-стайл: корпоративные дополнения

Рекомендация

Практичные правила из публичных стайл-гайдов, дополняющие v8std. Большинство автоматизируется диагностиками BSL LS.

Именование и префиксы объектов

Собственные объекты в типовых конфигурациях создаются под префиксом: КИ_ и ДД_ (по конфигурации). Префикс отличает наши объекты от типовых и снижает конфликты при обновлении и merge — это обязательное соглашение для командной разработки и аутсорса.

Именование в коде:

• Булевы — по истинному состоянию (ЕстьОшибки, ЭтоТоварТара), без отрицаний в названии флага.
• Процедуры — глагол по действию: СформироватьПроводки, ОбновитьКэш. Функции — сущность/результат: НомерДокумента(), ПараметрыПодключения().
• «Магические» сокращения без словаря команды запрещены — аутсорс уносит контекст из проекта вместе с собой.
• Длина строки — до ~120 символов (удобно для ревью и диффов).

Неправильно

// Неясно, что возвращает и зачем; параметры без смысла.
Функция ПолучитьДанные(П1, П2)
    // ...
КонецФункции

Правильно

// Ясно по имени и параметрам; описан контракт возврата.
// Возврат: Структура — Url, Логин, ПарольХранилищеКлюч.
Функция ПараметрыПодключенияКСервису(ИдентификаторСервиса) Экспорт
    // ...
КонецФункции

Структура кода и читаемость

• Guard-оператор вместо вложенных условий: ранний Возврат/Продолжить.
• Ограничивать уровень вложенности конструкций.
• Сложные условия выносить в переменные/функции с говорящими именами.
• Длинные сигнатуры (много параметров) → передавать структуру.
• Экспортные процедуры/функции — с описанием; скопированный из интернета код — с пометкой-источником.

Неправильно

Процедура ОбработатьДокумент(Документ)
    Если Документ <> Неопределено Тогда
        Если Не Документ.Проведен Тогда
            Если Документ.Сумма > 0 Тогда
                // сама логика — на четвёртом уровне вложенности
            КонецЕсли;
        КонецЕсли;
    КонецЕсли;
КонецПроцедуры

Правильно

Процедура ОбработатьДокумент(Документ)
    Если Документ = Неопределено Тогда
        Возврат;
    КонецЕсли;
    Если Документ.Проведен Или Документ.Сумма = 0 Тогда
        Возврат;
    КонецЕсли;
    // сама логика — на первом уровне
КонецПроцедуры

Запросы

• Не разбивать текст запроса построчной конкатенацией — это ломает конструктор запросов. Динамику собирать блоками, не ломающими конструктор (например, заменой (1 = 1) на условие).
• Не смешивать контексты: условия отбора — в ГДЕ, условия связи — в ПО.
• Проверка пустого результата — через Запрос.Выполнить().Пустой(), а не выборку.

Неправильно

// Конкатенация по кускам: конструктор запроса больше не откроется.
ТекстЗапроса = "ВЫБРАТЬ Ссылка ИЗ Справочник.Номенклатура";
Если ЕстьОтборПоВиду Тогда
    ТекстЗапроса = ТекстЗапроса + " ГДЕ ВидНоменклатуры = &Вид";
КонецЕсли;

Правильно

// Запрос целиком валиден для конструктора; динамика — заменой заглушки.
ТекстЗапроса =
    "ВЫБРАТЬ Ссылка
    |ИЗ Справочник.Номенклатура
    |ГДЕ (1 = 1)";
Если ЕстьОтборПоВиду Тогда
    ТекстЗапроса = СтрЗаменить(ТекстЗапроса, "(1 = 1)", "ВидНоменклатуры = &Вид");
КонецЕсли;

Исключения и логирование

• ВызватьИсключение; в блоке Исключение — без параметра (сохраняет стек).
• Не передавать текст ошибки строкой вместо записи в ЖР.
• Использовать ПодробноеПредставлениеОшибки(ИнформацияОбОшибке()), а не ОписаниеОшибки().

Транзакции и блокировки

• Каноничный блок: НачатьТранзакцию / Попытка / ЗафиксироватьТранзакцию / Исключение / ОтменитьТранзакцию / ВызватьИсключение.
• Управляемые блокировки при многопоточной загрузке — обязательны против дублей и гонок.

Зачем

Эти правила v8std формулирует обобщённо или не покрывает вовсе, а в ревью они всплывают чаще всего. Собранные в одном месте, они дают единый ориентир и подключаются к профилю диагностик.

Когда не применять

• Префиксы не нужны в самописных конфигурациях с нуля (там нет типовых объектов, от которых надо отличаться) — но нужны всегда в доработках типовых.
• Guard-операторы не самоцель: если условие одно и блок короткий, обычный Если читается не хуже.
• В код типовой конфигурации, который правится точечно (без рефакторинга), стиль окружающего кода важнее наших правил — не переформатируйте чужие модули «заодно».

См. также

• ADR — записи архитектурных решений
• Документация обновляется вместе с задачей
• Интерфейсные тексты через НСтр
• Исходники в git, линт и quality gate как условие мерджа
• Контуры баз — прод, тест, копии
• Обработка ошибок и логирование
• Общие модули и слои — где живёт логика
• Паттерны работы с БСП (вход, профили доступа, допреквизиты)
• Паттерны СКД (галочка-отбор, заголовок поля внешнего набора)
• Ревью и шаблон описания изменения
• Секреты в безопасном хранилище; техпользователь с минимальными правами
• Структура модуля и областей

• Структура модуля и областей
• Обработка ошибок и логирование
• Идемпотентность обработчиков обмена — управляемые блокировки против дублей.