Changed layout of sections

Author: artinnok

README.md

@@ -7,17 +7,17 @@
 
 ## Содержание
 - [Основные принципы при написании кода](#основные-принципы-при-написании-кода)
-- [Пакетный менеджер](#пакетный-менеджер)
-- [Форматирование кода](#форматирование-кода)
-- [Типизация](#типизация)
-- [Импорты](#импорты)
+- [Про код](#про-код)
 - [Размеры методов, функций и модулей](#размеры-методов-функций-и-модулей)
+- [Импорты](#импорты)
 - [Файлы `__init__.py`](#файлы-__init__py)
 - [Докстринги](#докстринги)
 - [Документация к REST API](#документация-к-rest-api)
-- [Про код](#про-код)
 - [Про Pull Request](#про-pull-request)
 - [Размер Pull Request](#размер-pull-request)
+- [Пакетный менеджер](#пакетный-менеджер)
+- [Форматирование кода](#форматирование-кода)
+- [Типизация](#типизация)
 
 
 ## Основные принципы при написании кода
@@ -26,6 +26,138 @@
 - **Очевидность** (представьте, когда подключится новый программист, насколько ему будет понятно, почему именно **так** написан этот код)
 
 
+## Про код
+**1 действие ~ 1 строка**
+
+На каждой строке надо постараться делать ровно одно действие. 
+
+Плохо ❌:
+```python
+# 1. 3 действия на одной строке - 3 вызова функции
+foo_result = foo(bar(spam(x)))
+
+# 2. 3 действия на одной строке - вызов функции foo, get_c, from_b
+foo_result = foo(a=a, b=b, c=get_c(from_b())
+
+# 3. 3 действия на одной строке - фильтрация по аргументам, условное получение элементов (через or), вызов метода .value
+result = [(a.value() or A, b or B) for a, b in iterator if a < b]
+
+# 4. 4 действия на одной строке - из библиотеки / переменной foo идет получение атрибута bar, получение атрибута spam, получение атрибута hello и вызов calculate_weather
+result = calculate_weather(foo.bar.spam.hello)
+```
+
+Хорошо ✅:
+```python
+# 1. делаем поочередный вызов каждой функции
+spam_result = spam(x)
+bar_result = bar(spam_result)
+foo_result = foo(bar_result)
+
+# 2. поочередно вызываем функции, результат пишем в переменную и используем ее при вызове foo
+from_b_result = from_b()
+c = get_c(from_b_result)
+foo_result = foo(a=a, b=b, c=c)
+
+# 3. последовательно проводим действия над списком - вначале фильтруем, вызываем метод .value у a, выбираем между элементами (or)
+filtered_result = ((a, b) for a, b in iterator if a < b)
+intermediate_result = ((a.value(), b) for a, b in filtered_result)
+result = [(a or A, b or B) for a, b in intermediate_result]
+
+# 4 . последовательно читаем атрибуты bar, spam, hello и вызываем функцию calculate_weather
+bar = foo.bar
+spam = bar.spam
+hello = spam.hello
+result = calculate_weather(hello)
+```
+
+
+**Почему?** Потому что код становится более читабельным, не нужно исполнять несколько выражений в голове во время чтения кода. Разбитый до простых атомных операций код воспринимается гораздо лучше, чем сложный уан-лайнер. Постарайтесь упростить свой код настолько, насколько это возможно - код чаще читается, чем пишется.
+
+
+## Размеры методов, функций и модулей
+
+Предельный размер метода или функции - **50** строк.
+Достижение предельного размера говорит о том, что функция (метод) делает слишком много - декомпозируйте действия внутри функции (метода). 
+
+
+Предельный размер модуля - **300** строк.
+Достижение предельного размера говорит о том, что модуль получил слишком много логики - декомпозируйте модуль на несколько.
+
+Длина строки - 100 символов.
+
+
+## Импорты
+
+Рекомендуемый способ импортирования - абсолютный. 
+
+Плохо ❌:
+```python
+# spam.py
+from . import foo, bar
+```
+
+Хорошо ✅:
+```python
+
+# spam.py
+from some.absolute.path import foo, bar
+```
+
+**Почему?** Потому что абсолютный импорт явно определяет локацию (путь) модуля, который импортируется. При релативном
+импорте всегда нужно помнить путь и вычислять в уме локацию модулей `foo.py`, `bar.py` относительно `spam.py`
+
+
+## Файлы `__init__.py`
+
+В `__init__.py` файлах пишем только импорты.
+
+**Почему?** Потому что `__init__.py` - последнее место, в которое посмотрит программист, который будет читать код в будущем.
+
+
+## Докстринги
+Рекомендуем добавлять докстринги в функции, методы и классы. 
+
+**Почему?** Потому что программист, который впервые увидит ваш код, сможет быстрее понять, что в нем происходит. 
+Код читается намного больше, чем пишется. 
+
+
+## Документация к REST API
+Рекомендуемый формат документации - [OpenAPI](https://www.openapis.org).
+Схема для OpenAPI должна генерироваться "на лету", чтобы обеспечивать клиентов API свежими изменениями.
+
+**Почему?** Потому что это один из распространенных форматов для документирования REST API, которая вышла из Swagger. Данный формат документации поддерживается большим количеством клиентов (Swagger, Postman, Insomnia Designer и многие другие). Также, рукописная документация имеет свойство быстро устаревать, а документация, которая генерируется напрямую из кода позволяет не думать о постоянном обновлении документации.
+
+
+## Про Pull Request
+**1 Pull Request = 1 issue**
+
+Один Pull Request должен решать ровно одно issue.
+
+**Почему?** Потому что ревьюверу сложнее держать контекст нескольких задач в голове и переключаться между ними.
+
+
+## Размер Pull Request
+Итоговый дифф PR не должен превышать +/- 600 измененных строк.
+
+Плохо ❌:
+
+![bad](https://user-images.githubusercontent.com/8825727/113953748-6fc7ba80-9853-11eb-9673-827995e54f73.png)
+```
+Дифф 444 + 333 = 777
+```
+
+Хорошо ✅:
+
+![good](https://user-images.githubusercontent.com/8825727/113953831-a30a4980-9853-11eb-854b-d4c4f6559f2c.png)
+```
+Дифф 222 + 111 = 333
+```
+
+
+**Почему?** Потому что чем больше PR - тем более он становится неконтролируемым и мерж производится "закрыв глаза и заткнув уши". 
+Также, большинству ревьюверов будет сложно воспринять такой объем изменений за один раз.
+
+
 ## Пакетный менеджер
 
 [poetry](https://python-poetry.org) - менеджер зависимостей и сборщик пакетов 
@@ -135,132 +267,3 @@ ignore_errors = True
 
 ```
 
-
-## Импорты
-
-Плохо ❌:
-```python
-# spam.py
-from . import foo, bar
-```
-
-Хорошо ✅:
-```python
-
-# spam.py
-from some.absolute.path import foo, bar
-```
-
-**Почему?** Потому что абсолютный импорт явно определяет локацию (путь) модуля, который импортируется. При релативном
-импорте всегда нужно помнить путь и вычислять в уме локацию модулей `foo.py`, `bar.py` относительно `spam.py`
-
-
-## Размеры методов, функций и модулей
-
-Предельный размер метода или функции - **50** строк.
-Достижение предельного размера говорит о том, что функция (метод) делает слишком много - декомпозируйте действия внутри функции (метода). 
-
-
-Предельный размер модуля - **300** строк.
-Достижение предельного размера говорит о том, что модуль получил слишком много логики - декомпозируйте модуль на несколько.
-
-Длина строки - 100 символов.
-
-
-## Файлы `__init__.py`
-
-В `__init__.py` файлах пишем только импорты.
-
-**Почему?** Потому что `__init__.py` - последнее место, в которое посмотрит программист, который будет читать код в будущем.
-
-
-## Докстринги
-Рекомендуем добавлять докстринги в функции, методы и классы. 
-
-**Почему?** Потому что программист, который впервые увидит ваш код, сможет быстрее понять, что в нем происходит. 
-Код читается намного больше, чем пишется. 
-
-
-## Документация к REST API
-Рекомендуемый формат документации - [OpenAPI](https://www.openapis.org).
-Схема для OpenAPI должна генерироваться "на лету", чтобы обеспечивать клиентов API свежими изменениями.
-
-**Почему?** Потому что это один из распространенных форматов для документирования REST API, которая вышла из Swagger. Данный формат документации поддерживается большим количеством клиентов (Swagger, Postman, Insomnia Designer и многие другие). Также, рукописная документация имеет свойство быстро устаревать, а документация, которая генерируется напрямую из кода позволяет не думать о постоянном обновлении документации.
-
-
-## Про код
-**1 действие ~ 1 строка**
-
-На каждой строке надо постараться делать ровно одно действие. 
-
-Плохо ❌:
-```python
-# 1. 3 действия на одной строке - 3 вызова функции
-foo_result = foo(bar(spam(x)))
-
-# 2. 3 действия на одной строке - вызов функции foo, get_c, from_b
-foo_result = foo(a=a, b=b, c=get_c(from_b())
-
-# 3. 3 действия на одной строке - фильтрация по аргументам, условное получение элементов (через or), вызов метода .value
-result = [(a.value() or A, b or B) for a, b in iterator if a < b]
-
-# 4. 4 действия на одной строке - из библиотеки / переменной foo идет получение атрибута bar, получение атрибута spam, получение атрибута hello и вызов calculate_weather
-result = calculate_weather(foo.bar.spam.hello)
-```
-
-Хорошо ✅:
-```python
-# 1. делаем поочередный вызов каждой функции
-spam_result = spam(x)
-bar_result = bar(spam_result)
-foo_result = foo(bar_result)
-
-# 2. поочередно вызываем функции, результат пишем в переменную и используем ее при вызове foo
-from_b_result = from_b()
-c = get_c(from_b_result)
-foo_result = foo(a=a, b=b, c=c)
-
-# 3. последовательно проводим действия над списком - вначале фильтруем, вызываем метод .value у a, выбираем между элементами (or)
-filtered_result = ((a, b) for a, b in iterator if a < b)
-intermediate_result = ((a.value(), b) for a, b in filtered_result)
-result = [(a or A, b or B) for a, b in intermediate_result]
-
-# 4 . последовательно читаем атрибуты bar, spam, hello и вызываем функцию calculate_weather
-bar = foo.bar
-spam = bar.spam
-hello = spam.hello
-result = calculate_weather(hello)
-```
-
-
-**Почему?** Потому что код становится более читабельным, не нужно исполнять несколько выражений в голове во время чтения кода. Разбитый до простых атомных операций код воспринимается гораздо лучше, чем сложный уан-лайнер. Постарайтесь упростить свой код настолько, насколько это возможно - код чаще читается, чем пишется.
-
-
-## Про Pull Request
-**1 Pull Request = 1 issue**
-
-Один Pull Request должен решать ровно одно issue.
-
-**Почему?** Потому что ревьюверу сложнее держать контекст нескольких задач в голове и переключаться между ними.
-
-
-## Размер Pull Request
-Итоговый дифф PR не должен превышать +/- 600 измененных строк.
-
-Плохо ❌:
-
-![bad](https://user-images.githubusercontent.com/8825727/113953748-6fc7ba80-9853-11eb-9673-827995e54f73.png)
-```
-Дифф 444 + 333 = 777
-```
-
-Хорошо ✅:
-
-![good](https://user-images.githubusercontent.com/8825727/113953831-a30a4980-9853-11eb-854b-d4c4f6559f2c.png)
-```
-Дифф 222 + 111 = 333
-```
-
-
-**Почему?** Потому что чем больше PR - тем более он становится неконтролируемым и мерж производится "закрыв глаза и заткнув уши". 
-Также, большинству ревьюверов будет сложно воспринять такой объем изменений за один раз.