steelmorgan/coding-standards

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

Правило 1: Именование переменных — 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: []