Update code_typification.md

2025-01-25 06:42:37 +02:00 · 2022-02-12 18:49:17 +03:00 · 2022-02-12 18:49:17 +03:00 · 064d8baf1c
commit 064d8baf1c
parent ddfcf6152d
1 changed files with 69 additions and 16 deletions
--- a/docs/checks/code_typification.md
+++ b/docs/checks/code_typification.md
@ -64,23 +64,25 @@
 Если Параметры.МоеСвойство > 0 Тогда // В этом месте тип МоеСвойство - Неопределено
 КонецЕсли;
 ...
-Параметры.Вставить("ДругоеСтвойство", Ложь); // Свойство инициализируется с начальным значением
+Параметры.Вставить("ДругоеСвойство", Ложь); // Свойство инициализируется с начальным значением

-Параметры.ДругоеСтвойство = 1; // Смена типа не происходит
+Параметры.ДругоеСвойство = 1; // Смена типа не происходит
 ...
-Если Параметры.ДругоеСтвойство Тогда // В этом месте тип свойства - Булево
+Если Параметры.ДругоеСвойство Тогда // В этом месте тип свойства - Булево
 КонецЕсли;
 ...

-Если ТипЗнч(Параметры.ДругоеСтвойство) = Тип("Число") Тогда 
-	Параметры.ДругоеСтвойство = Параметры.ДругоеСтвойство + 1; // В этом месте тип свойства - Булево
+Если ТипЗнч(Параметры.ДругоеСвойство) = Тип("Число") Тогда 
+	Параметры.ДругоеСвойство = Параметры.ДругоеСвойство + 1; // В этом месте тип свойства - Булево
 КонецЕсли;

 ```

 При фактической смене типа значения у свойства объекта, который допускает такое поведение в run-time `1С:Предприятия 8`, система типизации и анализа объектов данных в 1C:EDT не учитывает эту смену.

-В этом случае, правильным подходом является: указание начального типизированного значения, и не допускать сменя типа значения далее в коде.
+В этом случае, правильным подходом является: указание начального типизированного значения, и не допускать изменения типа значения далее в коде. Т.е., фактически - есть два варианта у переменных:
+1. Тип определен пользователем явно, и дальше он меняться не будет, а попытку изменения - можно будет отслеживать.
+2. Если тип неопределен явно, то он ВСЕГДА будет неопределен и далее, и плагин будет во всех местах его считать именно неопределенным. Фактически - данный подход запрещает использовать конструкцию ```Перем``` без явного указания типа в комментарии.

 ### Декларативная типизация

@ -98,6 +100,7 @@
 2. При этом, если помощник ввода не подсказывает нужные свойства - следует сначала уточнить типы (исправить типы) для текущего объекта и продолжить набор текста по известным свойствам.
 3. Использование типизации кода снижает потребность написания кода в режиме отладки с целью определения типов переменных, т.к. типы переменных подсказывает среда разработки.
 4. Для проверки, того, что объект имеет статический или динамический тип - необходимо выделить нужный объект и нажать `F2` для отображения описания объекта - перед именем объекта должен отображаться его тип.
+5. ВАЖНО! Типизирующие комментарии не могут переопределять типы, которые рассчитала EDT, а могут только их дополнять. Это значит, что если вы укажите в комментарии к функции что вы ожидаете на вход тип `ПолеВвода`, а в контекстной подсказке у вас показываются методы других типов, то это значит, что EDT нашла места вызова этой функции, в которых передается другой тип. И это убрать или переопределить типы - нельзя. 

 > **Внимание!** Контекстный помощник ввода работает при наборе документирующих комментариев.

@ -178,6 +181,10 @@
 - "Строгая типизация" не добавляет никаких функциональных возможностей в язык `1С:Предприятия 8`
 - Не добавляются "Интерфейсы" в язык `1С:Предприятия 8`

+Если подвести итог:
+- EDT сама старается рассчитывать типы, и если она смогла их рассчитать - изменить это вы уже не можете
+- Если EDT что-то не смогла рассчитать, то, при помощи комментария в коде вы можете РАСШИРИТЬ или ОПРЕДЕЛИТЬ тип. Вы не можете через комментарии типизации изменить тип, или полностью его переопределить.
+- Если некое свойство присутствует ХОТЯБЫ у одного типа, то даже если EDT рассчитает все типы кореектно - ошибки в этом месте не будет, например, EDT рассчитата что переменная может быть `Число|Массив`, то если вы напишите `Переменная.Количество()` - EDT не выдаст никакой ошибки, так как этот метод есть хотябы у одного найденого типа.

 #### Включение строгой типизации

@ -223,15 +230,15 @@

 Функция ФункцияРазличныхТипов(Флаг)
 	Если Флаг Тогда
-		Вовзрат "";
+		Вовзрат Новый Массив;
 	Иначе
 		Вовзрат 10;
 	КонецЕсли;
 КонецФункции
 ```

-В данном примере, у переменной `МояПеременная` будет 2 расчетный и один декларативный тип: `Строка, Число, Булево`.
-
+В данном примере - EDT сама рассчитает 2 типа - `Массив|Число`, и, при помощи коментария - мы расширим тип переменной `МояПеременная` до третьего типа - `Булево`.
+Теперь - EDT позволит вам выполнять любые действия над этой перменной, если это действие можно выполнить хотябы над одним типом (рассчитанным EDT, или добавленным вами через типизирующий комментарий).
 ### Сокращение типа локальной переменной или параметра

 - Можно безопасно сократить (или фактически установить для статического анализатора) тип локальной переменной метода, входящего параметра или переменной модуля (объекта, формы) метода через проверку типа:
@ -244,6 +251,52 @@

 при этом внутри условия переменная будет указанного в проверке типа, как в рантайме, так и для статического анализатора. Условие проверки должно быть простым.

+Если есть задача переопределения типа, то тогда это надо делать явно. Переопределить типы через комментарии - не возможно! Где и когда это может быть полезно - например, есть некая функция, куда вы передаете объект документа, и внутри этой функции рассчитываются какие-то данные по реквизитам этого объекта, и там же идет вызов неких функций из этого объекта:
+```bsl
+// @strict-types
+// Тут я где то по коду вызываю функцию, которая ниже.
+Ответ = МакетПечати(Документы.Заказ.СоздатьДокумент());
+
+// Тест.
+// 
+// Параметры:
+//  Док - ДокументОбъект.Заказ - Это строка
+// 
+// Возвращаемое значение:
+//  ТабличныйДокумент - Тест
+&НаСервереБезКонтекста
+Функция МакетПечати (Док)
+	Док.Автор = Справочники.Пользователи.ПустаяСсылка();
+	Макет = Док.ВернутьМакет();
+	Возврат Макет;
+КонецФункции
+```
+Все отработает корректно, никаких проблем не будет. НО! Как только в коде появится еще и вот такая строка:
+```bsl
+Ответ = МакетПечати(Документы.РасходТовара.СоздатьДокумент());
+```
+Тогда тогда, переменная `Док` будет уже иметь два расчетных типа. И самое важно - нигде в этом коде ошибок не будет. При этом - у документа `РасходТовара` нет реквизита `Автор` и нет функции в модуле объекта `ВернутьМакет`. При этом - никаких ошибок нигде не будет! Но что делать, если есть цель таки выяснить - будут ли проблемы при передачи нового типа в функцию? Да, возможность есть, если переписать код вот так:
+
+```bsl
+Функция МакетПечати (Док)
+	// ТАК БЫЛО. Тут не будет никаких ошибок
+	Док.Автор = Справочники.Пользователи.ПустаяСсылка();
+	Макет = Док.ВернутьМакет();
+
+	// ТАК СТАЛО. 
+	Если ТипЗнч(Док) = Тип("ДокументОбъект.Заказ") Тогда
+		// Тут ошибок не будет, так как у заказа есть все функции и реквизиты
+		Док.Автор = Справочники.Пользователи.ПустаяСсылка();
+		Макет = Док.ВернутьМакет();
+	Если ТипЗнч(Док) = Тип("ДокументОбъект.РасходТовара") Тогда
+		// А вот тут уже будет ошибка, так как Док будет иметь только один тип, и у этого типа - нет реквизита и функции
+		Док.Автор = Справочники.Пользователи.ПустаяСсылка();
+		Макет = Док.ВернутьМакет();
+	КонецЕсли;
+	
+	Возврат Макет;
+КонецФункции
+```

 ## Возможности типизирующих документирующих комментариев

@ -333,7 +386,7 @@ ReturnSection:     # Секция описания возвращаемого з
 Процедура ОбработкаОбъекта(Объект)
 ```

-В секции параметры, после ключевого слова - обязательно идет двоеточие
+В секции параметры, после ключевого слова `Параметры` - обязательно идет двоеточие

 ```bsl
 // Описание метода
@ -371,7 +424,7 @@ ReturnSection:     # Секция описания возвращаемого з
 Процедура ОбработкаОбъекта(Объект)
 ```

-Возможно указание описания для каждого типа поля/параметра, когда каждый тип записан с новой строки, через дефис-минус. Не допускается использование различных видов "тире" (длинных, коротых, средних и т.д.)
+Возможно указание описания для каждого типа поля/параметра, когда каждый тип записан с новой строки, через дефис-минус. Не допускается использование различных видов "тире" (длинных, коротких, средних и т.д.)

 ```bsl
 // Параметры:
@ -449,7 +502,7 @@ ReturnSection:     # Секция описания возвращаемого з
 Функция ОбработкаОбъекта(Объект)
 ```

-Декларацию списока типов возвращаемого значения нужно записывать явно с дефисом в конце или с но
+Декларацию списка типов возвращаемого значения нужно записывать явно с дефисом в конце или с новой строки

 ```bsl
 // Возвращаемое значение:
@ -474,7 +527,7 @@ ReturnSection:     # Секция описания возвращаемого з
 Процедура ОбработкаОбъекта(Объект)
 ```

-Ссылка на тип не кобминируется с описанием для текущего элемента, должны быть записаны вместо типа
+Ссылка на тип не комбинируется с описанием для текущего элемента, должны быть записаны вместо типа

 ```bsl
 // Параметры:
@ -492,7 +545,7 @@ ReturnSection:     # Секция описания возвращаемого з
 Функция ОбработкаОбъекта(Объект)
 ```

-В возвращаемом значении функции можно указывать ссылки на локальные не экспортные функции конструткоры объектов данных, если функция должна возвращать заполненный объект, но модуль не должен позволять через API создавать новый пустой объект данных
+В возвращаемом значении функции можно указывать ссылки на локальные не экспортные функции конструкторы объектов данных, если функция должна возвращать заполненный объект, но модуль не должен позволять через API создавать новый пустой объект данных

 ```bsl
 // Экспорт из модуля типа объекта в функции, создающем объект и заполняющем значения, 
@ -595,7 +648,7 @@ ReturnSection:     # Секция описания возвращаемого з
 ##### Ссылка на Текущие данные динамического списка формы

 Использование ссылки на тип текущих данных динамического списка на форме не поддерживается в документирующих комментариях.
-В место этого следует передавать сам элемент формы и далее обрабатывать `ТекущиеДанные`
+Вместо этого следует передавать сам элемент формы и далее обрабатывать `ТекущиеДанные`

 ПРАВИЛЬНО:

@ -622,7 +675,7 @@ ReturnSection:     # Секция описания возвращаемого з

 #### Ссылка на типы объектов кода

-В ссылка типизирующих комментариев можно пере-использовать описанные типы из возвращаемого значения функций или входящих параметров метода.
+В ссылка типизирующих комментариев можно переиспользовать описанные типы из возвращаемого значения функций или входящих параметров метода.

 ##### Ссылка на тип параметра метода в модели менеджера, объекта, общем модуле