v8: Рекомендации по оформлению кода 1Сv8
Ключевые слова: Рекомендации, внутренний язык, язык запросов, оформление
Pаголовки методов.
В меню контекстной подсказки при наведении мышью на метод отображается только его описание! Т.е. пока не перейдешь к определению самого метода, не узнаешь о его параметрах ничего, если они не будут должным образом описаны в заголовке. В типовых в большинстве случаев заголовок описывает параметры, следуя рекомендациям самой же 1С. И я делал также, но частенько меня расстраивал факт невозможности узнать, является ли параметр метода необходимым и какое значение по умолчанию он имеет. И я решил доработать заголовок метода:
// <Описание функции>
//
// Параметры:
// *<Параметр1> – <Тип.Вид>, *<ЗначениеПоУмолчанию1> – <описание параметра1>
// <продолжение описания параметра1>;
// *<Параметр2> – <Тип.Вид>, *<ЗначениеПоУмолчанию2> – <описание параметра2>
// <продолжение описания параметра2>.
// Возвращаемое значение:
// <Значение1> - <Тип.Вид> – <описание значения1> - <описание условия1>;
// <Значение2> - <Тип.Вид> - <описание значения2> – иначе.
//
Звездочка перед параметром обозначает его необязательность. После звездочки, следующей за типом параметра указывается значение по умолчанию.
Пример
// Получает список реквизитов объекта БД.
//
// Параметры:
// пОбъект – ОбъектБД;
// *СписокВыбора – СписокЗначений, *Неопределено – если нужно заполнить уже имеющийся список;
// *ЛиВключатьТолькоЧитаемые - Булево, *Ложь - включать ли в список только читаемые реквизиты;
// *ЛиВключатьНедоступные - Булево, *Ложь - включать ли в список недоступные (группы/элементы)
// реквизиты;
// *ЛиСортировать - Булево, *Ложь - отсортировать ли по представлению.
//
// Возвращаемое значение:
// СписокЗначений – содержащий в качестве значений имена реквизитов.
//
Функция ЛксПолучитьСписокРеквизитовОбъектаБД(пОбъект, пСписокВыбора = Неопределено,
ЛиВключатьТолькоЧитаемые = Ложь, ЛиВключатьНедоступные = Ложь, ЛиСортировать = Ложь) Экспорт
Логические выражения
Рассмотрим пример сложного логического выражения:
Если А = Б И В > Г И (Д = Неопределено ИЛИ НЕ Ж = З ИЛИ НЕ (К = Л И М = 0)) Тогда
<Тело положительной ветви условия>
Иначе
<Тело отрицательной ветви условия>
КонецЕсли;
В таком виде оно выглядит компактно и отностительно легко воспринимается.
Но, если мы заменим краткие малоинформативные идентификаторы переменных длинными многоинформативными (не говоря уже о разыменовывании), то ситуация заметно изменится:
Если Котрагент = ПоследнийКонтрагент И СуммаДокументаРеализации > СуммаДляПредоставленияСкидки И (ЗаказПокупателя = Неопределено ИЛИ НЕ ДеньНедели = ДеньНеделиВоскресение ИЛИ НЕ (НеделяПродажи = ПоследняяНеделяМесяца И СуммаПродажиПоРасходникам = 0)) Тогда
<Тело положительной ветви условия>
Иначе
<Тело отрицательной ветви условия>
КонецЕсли;
Теперь уже стало очень неудобно воспринимать и редактировать это условие.
Естественно, нужно разбить условие на строки, только вот как? Обычно разбивают так:
Если Котрагент = ПоследнийКонтрагент И СуммаДокументаРеализации > СуммаДляПредоставленияСкидки
И (ЗаказПокупателя = Неопределено ИЛИ НЕ ДеньНедели = ДеньНеделиВоскресение ИЛИ НЕ
(НеделяПродажи = ПоследняяНеделяМесяца И СуммаПродажиПоРасходникам = 0)) Тогда
<Тело положительной ветви условия>
Иначе
<Тело отрицательной ветви условия>
КонецЕсли;
Такую конструкцию тяжело воспринимать и модифицировать.
В случае внутреннего языка это условие целесообразно разбить на множество мелких условий:
Флаг = Ложь;
Если Котрагент = ПоследнийКонтрагент И СуммаДокументаРеализации > СуммаДляПредоставленияСкидки Тогда
Если ЗаказПокупателя = Неопределено Тогда
Флаг = Истина;
ИначеЕсли Не ДеньНедели = ДеньНеделиВоскресение Тогда
Флаг = Истина;
ИначеЕсли Не (НеделяПродажи = ПоследняяНеделяМесяца И СуммаПродажиПоРасходникам = 0) Тогда
Флаг = Истина;
КонецЕсли;
КонецЕсли;
Если Флаг Тогда
<Тело положительной ветви условия>
Иначе
<Тело отрицательной ветви условия>
КонецЕсли;
Я рекомендую такую конструкцию.
Если Истина
И Контрагент = ПоследнийКонтрагент
И СуммаДокументаРеализации > СуммаДляПредоставленияСкидки
И (Ложь
Или ЗаказПокупателя = Неопределено
Или Не ДеньНедели = ДеньНеделиВоскресение
Или Не (Истина
И НеделяПродажи = ПоследняяНеделяМесяца
И СуммаПродажиПоРасходникам = 0))
Тогда
<Тело положительной ветви условия>
Иначе
<Тело отрицательной ветви условия>
КонецЕсли;
Она компактее. Она позволяет быстрее воспринимать сложное условие в целом. А главное - ее легче модифицировать за счет правила "одна строка - одно условие", но правда с одним исключением, о котором позже.
Аналогично с языком запросов. Тут этот подход намного актуальнее, т.к. здесь уже мы
не можем применить альтернативу как разбивку на множество Если ... Тогда.
Итак обычная запись логического условия на языке запросов:
ГДЕ Котрагент = Контрагенты.ПоследнийКонтрагент И СуммаДокументаРеализации > СуммаДляПредоставленияСкидки
И (ЗаказПокупателя ЕСТЬ NULL ИЛИ НЕ ДеньНедели = &ДеньНеделиВоскресение ИЛИ НЕ
(НеделяПродажи = &ПоследняяНеделяМесяца И СуммаПродажиПоРасходникам = 0))
Моя конструкция выглядит так:
ГДЕ Истина
И Контрагент = Контрагенты.ПоследнийКонтрагент
И СуммаДокументаРеализации > СуммаДляПредоставленияСкидки
И (Ложь
Или ЗаказПокупателя ЕСТЬ NULL
Или Не ДеньНедели = &ДеньНеделиВоскресение
Или Не (Истина
И НеделяПродажи = &ПоследняяНеделяМесяца
И СуммаПродажиПоРасходникам = 0))
Как вы уже поняли, позже любой программист, сможет легко вставить в любую непоследнюю строку или закомментировать любую непоследнюю строку в любой группе. Вот то исключение, о котором я уже писал -последняя строка группы в общем случае содержит закрывающую скобку, поэтому сначала нужно будет спозиционироваться на эту закрывающую скобку и временно перенести ее на следующую строку, нажав перед ней <ENTER>:
Или Не (Истина
И НеделяПродажи = ПоследняяНеделяМесяца
И СуммаПродажиПоРасходникам = 0)
)
Теперь вы можете вставить или закомментировать последнюю строку на равне с остальными.
Или Не ДеньНедели = ДеньНеделиВоскресение
Или Не (Истина
И НеделяПродажи = ПоследняяНеделяМесяца
И СуммаПродажиПоРасходникам = 0)
Или Бонус > СреднийБонус
)
После выполнения вставки возвращаем скобку в конец последней строки.
Или Не ДеньНедели = ДеньНеделиВоскресение
Или Не (Истина
И НеделяПродажи = ПоследняяНеделяМесяца
И СуммаПродажиПоРасходникам = 0)
Или Бонус > СреднийБонус))
Если же вы закомментировали последнюю строку группы, то, ее следует перенести на непоследнее место в группе, если это не нарушает логики.
// Или Не (Истина
// И НеделяПродажи = ПоследняяНеделяМесяца
// И СуммаПродажиПоРасходникам = 0)
Или Не ДеньНедели = ДеньНеделиВоскресение)
Иначе скобку следует оставить на отдельной строке, т.к. последняя строка группы закомментирована.
Или Не ДеньНедели = ДеньНеделиВоскресение
// Или Не (Истина
// И НеделяПродажи = ПоследняяНеделяМесяца
// И СуммаПродажиПоРасходникам = 0)
)
|