From 8985851938b1b36ae3d4734d42a21fe22f63c777 Mon Sep 17 00:00:00 2001
From: Vadim Nifadev <36514612+nifadyev@users.noreply.github.com>
Date: Thu, 19 Sep 2024 08:54:24 +0300
Subject: [PATCH] Add recommendation about type annotations

---
 EN.md | 7 +++++++
 RU.md | 7 +++++++
 2 files changed, 14 insertions(+)

diff --git a/EN.md b/EN.md
index b954b9b..2f064b5 100644
--- a/EN.md
+++ b/EN.md
@@ -186,6 +186,13 @@ We recommend adding docstrings to functions, methods, and classes.
 Code is read much more than it is written.
 
 
+### Type Annotations
+
+Annotating new code is strongly encouraged. Existing codebase is recommended to annotate gradually. It is also advised to use `static type checker` on `pre-commit` or `CI` stage but allow proceeding with invalid annotations because sometimes it takes a lot of effort to debug and annotate code.
+
+**Why?** Typed code is better self-documented. There is no need to guess the object's type or use `isinstance`, modern IDEs work perfectly with annotated object types. Moreover, annotations reduce error rate. Warnings and errors are shown by `static type checker` during coding instead of catching errors on running project. Unit testing is also much easier if you know what types are expected.
+
+
 ## About Pull Requests
 
 ### Creating Pull Requests
diff --git a/RU.md b/RU.md
index f4011e0..e02d379 100644
--- a/RU.md
+++ b/RU.md
@@ -186,6 +186,13 @@ from some.absolute.path import foo, bar
 Код читается намного больше, чем пишется. 
 
 
+### Аннотации типов
+
+Крайне рекомендуется типизировать новый код. Существующую кодовую базу следует типизировать постепенно. Не будет лишним использовать `статический анализатор типов` на стадии `pre-commit` и/или `CI` с возможностью пропустить проверку, так как зачастую требуется много времени для типизирования и отладки кода.
+
+**Почему?** Типизированный код является актуальной "документацией". Не нужно угадывать тип объекта или использовать `isinstance`, современные IDE прекрасно считывают тип аннотированных объектов. К тому же типизированный код снижает число ошибок. Предупреждения и ошибки о неправильном типе возникают при запуске `статического анализатора типов` во время написания кода, а не в процессе взаимодействия с запущенным проектом. Юнит тесты писать гораздо проще, если знать, какие типы данных ожидаемы.
+
+
 ## Про Pull Request
 
 ### Создание Pull Request