coding-standards

name	coding-standards
description	При написании или ревью BSL применять стандарты 1С
alwaysApply	false

Стандарты кодирования BSL (1С)

Правило 1: Именование идентификаторов — CamelCase на русском языке

Стандарт ИТС: «Тексты модулей» — имена на русском, ВерблюжийРегистр. Для процедур, функций, переменных и параметров используйте CamelCase с заглавной первой буквой.

Элемент	Формат	Пример
Переменная	СуществительноеИлиФраза	КоличествоСтрок, ДатаНачалаПериода
Процедура	ГлагольнаяФраза	ЗаполнитьТабличнуюЧасть, УстановитьОтбор
Функция	СуществительноеИлиВопрос	ПолучитьСписокДокументов, ЭтоНовый
Булева переменная	Утвердительная форма	ЭтоНовый, РазрешеноРедактирование, ЕстьОшибки
Параметр	КакПеременная	ДокументСсылка, РежимОткрытия

Именование процедур и функций

• Процедуры называйте глагольной фразой в неопределенной форме: ЗаполнитьТабличнуюЧасть, УстановитьОтбор.
• Функции называйте по возвращаемому значению, без указания типа в имени: СписокДокументов, ЭтоНовый.
• Функции-конструкторы начинайте со слова Новый: НовыйПараметрыОтбора.
• Функции-проверки начинайте с Это, Есть, Используется, Включено или используйте причастие: ЭтоНовый, ЕстьОшибки, ЗаполненоЗначение.
• Если важен способ получения результата, допустимо имя функции от глагола: ПолучитьСписокДокументов.
• Если функция используется ради действия, а результат является побочным эффектом, называйте ее как процедуру.

Процедура ЗаполнитьТабличнуюЧастьТовары(ДокументОбъект, ДанныеЗаполнения)

    КоличествоСтрок = ДанныеЗаполнения.Количество();
    ЕстьОшибки = Ложь;

    Для Каждого СтрокаДанных Из ДанныеЗаполнения Цикл
        НоваяСтрока = ДокументОбъект.Товары.Добавить();
        НоваяСтрока.Номенклатура = СтрокаДанных.Номенклатура;
        НоваяСтрока.Количество = СтрокаДанных.Количество;
    КонецЦикла;

КонецПроцедуры

---

Правило 2: Структура модуля — секции интерфейса и реализации

Стандарт ИТС: «Структура модуля» — области (#Область) в определённом порядке.

Порядок секций общего модуля

#Область ПрограммныйИнтерфейс

// Экспортные процедуры и функции — публичный API модуля.

Функция ПолучитьКурсВалюты(Валюта, ДатаКурса) Экспорт
    // ...
КонецФункции

#КонецОбласти

#Область СлужебныйПрограммныйИнтерфейс

// Экспортные процедуры для вызова только из других модулей данной подсистемы.

Функция ПересчитатьКурсВнутренний(ПараметрыПересчета) Экспорт
    // ...
КонецФункции

#КонецОбласти

#Область СлужебныеПроцедурыИФункции

// Внутренняя реализация. Не экспортные.

Функция СформироватьЗапросКурса(Валюта, Дата)
    // ...
КонецФункции

#КонецОбласти

Порядок секций модуля объекта

#Область ОписаниеПеременных

Перем МассивИзменённыхРеквизитов;

#КонецОбласти

#Область ОбработчикиСобытий

Процедура ОбработкаЗаполнения(ДанныеЗаполнения, ТекстЗаполнения, СтандартнаяОбработка)
    // ...
КонецПроцедуры

Процедура ПередЗаписью(Отказ)
    // ...
КонецПроцедуры

#КонецОбласти

#Область СлужебныеПроцедурыИФункции
#КонецОбласти

#Область Инициализация

МассивИзменённыхРеквизитов = Новый Массив;

#КонецОбласти

---

Правило 3: Директивы компиляции — &НаКлиенте, &НаСервере, &НаСервереБезКонтекста

При вызове &НаСервере платформа сериализует весь контекст формы туда-обратно. &НаСервереБезКонтекста передаёт только параметры — радикально меньше трафика.

Директива	Где выполняется	Доступ к данным формы	Когда использовать
&НаКлиенте	Клиент (тонкий/веб)	Да (клиентская копия)	Интерактивная логика: диалоги, навигация
&НаСервере	Сервер	Да (полный контекст формы)	Нужен доступ к реквизитам формы + БД
&НаСервереБезКонтекста	Сервер	Нет	Запросы к БД, вычисления без данных формы
&НаКлиентеНаСервереБезКонтекста	И клиент, и сервер	Нет	Чистые вычисления, валидация без БД

---

Правило 6: Не затеняйте глобальный контекст

Локальная переменная с именем глобальной коллекции скрывает менеджер — дальше в коде обращения к нему дадут ошибку.

// Правильно — конкретное имя
МассивДокументовКОбработке = Новый Массив;
СправочникНоменклатура = Справочники.Номенклатура;

Список зарезервированных имён (не использовать для переменных)

Документы, Справочники, Регистры, Перечисления, ПланыОбмена, ПланыВидовХарактеристик, ПланыВидовРасчета, ПланыСчетов, БизнесПроцессы, Задачи, Обработки, Отчеты, Константы, ПараметрыСеанса, РегистрыСведений, РегистрыНакопления, РегистрыБухгалтерии, РегистрыРасчета

---

Правило 7: Конкатенация строк — не используйте «+» в циклах

В BSL строки иммутабельны. Строка1 + Строка2 в цикле из N итераций даёт O(N^2) по памяти и времени — каждая итерация копирует всё предыдущее.

Стандарт ИТС: «Эффективная работа со строками».

// O(N) — массив + СтрСоединить()
ЧастиСтроки = Новый Массив;
Для Каждого Элемент Из КоллекцияДанных Цикл
    ЧастиСтроки.Добавить(Элемент.Наименование);
КонецЦикла;
РезультатСтрока = СтрСоединить(ЧастиСтроки, ", ");

// Для фиксированного числа подстановок — СтрШаблон() (до 10 параметров)
ТекстСообщения = СтрШаблон(
    НСтр("ru = 'Документ %1 от %2 на сумму %3 руб.'"),
    НомерДокумента,
    Формат(ДатаДокумента, "ДЛФ=D"),
    Формат(Сумма, "ЧДЦ=2"));

---

Правило 8: Области (#Область) для организации кода

Стандарт ИТС: «Структура модуля» — обязательные стандартные области.

Стандартные области для модуля формы

#Область ОписаниеПеременных
#КонецОбласти

#Область ОбработчикиСобытийФормы
#КонецОбласти

#Область ОбработчикиСобытийЭлементовШапкиФормы
#КонецОбласти

#Область ОбработчикиСобытийЭлементовТаблицыФормыТовары
#КонецОбласти

#Область ОбработчикиКомандФормы
#КонецОбласти

#Область СлужебныеПроцедурыИФункции
#КонецОбласти

Правила: не вкладывать глубже 2 уровней; не создавать пустые области; использовать стандартные имена из ИТС (IDE и инструменты анализа на них опираются).

---

Правило 9: Комментарии — объясняйте «зачем», а не «что»

Стандарт ИТС: «Описание процедур и функций» — экспортные процедуры ОБЯЗАНЫ иметь комментарий-описание.

Описание экспортной функции

// Возвращает курс валюты на указанную дату.
// Если на указанную дату курс не установлен, возвращает курс на ближайшую предыдущую дату.
//
// Параметры:
//  Валюта   - СправочникСсылка.Валюты - валюта, курс которой нужно получить.
//  ДатаКурса - Дата - дата, на которую нужен курс.
//              Если не указана, используется текущая дата сеанса.
//
// Возвращаемое значение:
//  Число - курс валюты. 0 если курс не найден.
//
Функция ПолучитьКурсВалюты(Валюта, ДатаКурса = Неопределено) Экспорт

Комментарий «зачем»

// Сумму округляем до копеек, потому что бухгалтерский учёт не допускает дробных копеек,
// а при пересчёте НДС могут возникнуть дроби.
СуммаНДС = Окр(СуммаБезНДС * СтавкаНДС / 100, 2);

---

Правило 10: Используйте НСтр() для строковых литералов

Все строки, отображаемые пользователю, оборачиваются в НСтр() — для локализуемости.

Стандарт ИТС: «Использование функции НСтр()».

ТекстПредупреждения = НСтр("ru = 'Документ не может быть проведён. Не заполнена дата.'");

// С параметрами — НСтр() + СтрШаблон()
ТекстСообщения = СтрШаблон(
    НСтр("ru = 'Остаток товара ""%1"" на складе: %2 %3'"),
    Номенклатура,
    Остаток,
    ЕдиницаИзмерения);

---

Правило 11: Одна процедура — одна ответственность

Процедура свыше 100 строк — сигнал к декомпозиции. Разделение на мелкие функции с говорящими именами делает код самодокументируемым.

Процедура ОбработкаПроведения(Отказ, РежимПроведения)

    ИнициализироватьДанныеДокумента();
    ПроверитьЗаполнениеРеквизитов(Отказ);

    Если Не Отказ Тогда
        СформироватьДвижения(Отказ);
    КонецЕсли;

КонецПроцедуры

---

Правило 12: Явная типизация параметров в комментариях

BSL динамически типизирован. Описание типов в комментарии к экспортной функции — единственный способ документировать контракт.

// Создаёт новый элемент справочника «Номенклатура» с заполнением по умолчанию.
//
// Параметры:
//  ДанныеЗаполнения - Структура - содержит поля:
//    * Наименование      - Строка - наименование номенклатуры (обязательно).
//    * ВидНоменклатуры    - ПеречислениеСсылка.ВидыНоменклатуры - вид (обязательно).
//    * ЕдиницаИзмерения  - СправочникСсылка.ЕдиницыИзмерения - ед. изм. Необязательно,
//                          по умолчанию «шт.».
//    * Артикул            - Строка - артикул. Необязательно.
//
// Возвращаемое значение:
//  СправочникСсылка.Номенклатура - ссылка на созданный элемент.
//
Функция СоздатьНоменклатуру(ДанныеЗаполнения) Экспорт

---

Правило 13: Не используйте «Выполнить()» и «Вычислить()» без крайней необходимости

Угроза безопасности (аналог eval), невидимы для статического анализа, трудны в отладке.

// Правильно — прямой вызов через метаданные
МенеджерОбъекта = ОбщегоНазначения.МенеджерОбъектаПоСсылке(СсылкаНаОбъект);

---

Правило 14: Магические числа и строки — выносите в параметры

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

// Правильно — перечисление, значение самодокументировано
Если Документ.Статус = Перечисления.СтатусыДокументов.Согласован Тогда
    // ...
КонецЕсли;

// Или константа для настраиваемых значений
МаксимальноеКоличествоПопыток = Константы.МаксимальноеКоличествоПопытокОтправки.Получить();

---

Правило 15: Явные JOIN вместо точечной нотации через ссылки

Цепочки ссылок создают неявные JOIN. При составных типах платформа делает JOIN ко всем возможным таблицам.

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

Неправильно — обращение через точку в цикле (N+1)

Для Каждого СтрокаТоваров Из Документ.Товары Цикл
    ВидНоменклатуры = СтрокаТоваров.Номенклатура.ВидНоменклатуры;
    ЕдиницаИзмерения = СтрокаТоваров.Номенклатура.ЕдиницаИзмерения;
КонецЦикла;

---

Правило 16: Открывайте формы через ОткрытьФорму()

ПолучитьФорму() доступен в клиентском коде управляемого приложения, но он лишь создаёт форму и возвращает её без показа, оставляя управление жизненным циклом на разработчике. Для открытия формы предпочитайте ОткрытьФорму() — она создаёт и показывает форму за один вызов.

ПараметрыФормы = Новый Структура;
ПараметрыФормы.Вставить("Ключ", ДокументСсылка);

ОткрытьФорму("Документ.РеализацияТоваровУслуг.ФормаОбъекта",
    ПараметрыФормы,
    ЭтотОбъект,
    ,
    ,
    ,
    Новый ОписаниеОповещения("ПослеЗакрытияФормыДокумента", ЭтотОбъект));

---

Правило 17: Бизнес-логика не должна жить в модуле формы

Логику записи и проверок размещайте в модуле объекта — для тестируемости и повторного использования.

// Модуль объекта документа
Процедура ПередЗаписью(Отказ)
    Для Каждого Строка Из Товары Цикл
        Строка.Сумма = Строка.Количество * Строка.Цена;
    КонецЦикла;
КонецПроцедуры

---

Правило 18: Не проглатывайте исключения

См. error-handling, правило 1.

---

Правило 19: Агрегируйте серверные вызовы из формы

См. form-patterns.

---

Верификация через Напарника

• Проверка кода на стандарты и аналоги БСП: ask_ai_assistant (шаблон VALIDATE_BSL из buddy-prompting). Отдать фрагмент кода — получить нарушения стандартов и рекомендации по замене на методы БСП/платформы.
• Проверка стандарта по первоисточнику: ask_ai_assistant (шаблон SEARCH_ITS из buddy-prompting). При расхождении навыка с ИТС — приоритет у ИТС.

---

depends_on: []