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