Split sections on sub-sections

Author: artinnok

README.md

@@ -6,30 +6,37 @@
 [<img src="https://evrone.com/logo/evrone-sponsored-logo.png" width=300>](https://evrone.com/?utm_source=github.com&utm_campaign=evrone-python-codestyle)
 
 ## Содержание
-- [Основные принципы при написании кода](#основные-принципы-при-написании-кода)
 - [Про код](#про-код)
-- [Размеры методов, функций и модулей](#размеры-методов-функций-и-модулей)
-- [Импорты](#импорты)
-- [Файлы `__init__.py`](#файлы-__init__py)
-- [Докстринги](#докстринги)
-- [Документация к REST API](#документация-к-rest-api)
+  - [Основные принципы](#основные-принципы)
+  - [Атомарность операций](#атомарность-операций)
+  - [Размеры методов, функций и модулей](#размеры-методов-функций-и-модулей)
+  - [Импорты](#импорты)
+  - [Файлы `__init__.py`](#файлы-__init__py)
+  - [Докстринги](#докстринги)
 - [Про Pull Request](#про-pull-request)
-- [Размер Pull Request](#размер-pull-request)
-- [Пакетный менеджер](#пакетный-менеджер)
-- [Форматирование кода](#форматирование-кода)
-- [Типизация](#типизация)
+  - [Создание Pull Request](#создание-pull-request)
+  - [Размер Pull Request](#размер-pull-request)
+- [Про тулинг](#про-тулинг)
+  - [Пакетный менеджер](#пакетный-менеджер)
+  - [Форматирование кода](#форматирование-кода)
+  - [Pre-commit хуки](#pre-commit-хуки)
+  - [Типизация](#типизация)
+- [Прочее](#прочее)
+  - [Документация к REST API](#документация-к-rest-api)
 
 
-## Основные принципы при написании кода
+## Про код
+
+### Основные принципы
 - **Поддерживаемость** (представьте, сможете ли вы понять свой код через год или через два)
 - **Простота** (между сложным и простым решением следует выбрать простое)
 - **Очевидность** (представьте, когда подключится новый программист, насколько ему будет понятно, почему именно **так** написан этот код)
 
 
-## Про код
+### Атомарность операций
 **1 действие ~ 1 строка**
 
-На каждой строке надо постараться делать ровно одно действие. 
+Постарайтесь делать атомарные операции в коде - на каждой строке ровно **одно** действие. 
 
 Плохо ❌:
 ```python
@@ -74,7 +81,7 @@ result = calculate_weather(hello)
 **Почему?** Потому что код становится более читабельным, не нужно исполнять несколько выражений в голове во время чтения кода. Разбитый до простых атомных операций код воспринимается гораздо лучше, чем сложный уан-лайнер. Постарайтесь упростить свой код настолько, насколько это возможно - код чаще читается, чем пишется.
 
 
-## Размеры методов, функций и модулей
+### Размеры методов, функций и модулей
 
 Предельный размер метода или функции - **50** строк.
 Достижение предельного размера говорит о том, что функция (метод) делает слишком много - декомпозируйте действия внутри функции (метода). 
@@ -86,7 +93,7 @@ result = calculate_weather(hello)
 Длина строки - 100 символов.
 
 
-## Импорты
+### Импорты
 
 Рекомендуемый способ импортирования - абсолютный. 
 
@@ -107,36 +114,31 @@ from some.absolute.path import foo, bar
 импорте всегда нужно помнить путь и вычислять в уме локацию модулей `foo.py`, `bar.py` относительно `spam.py`
 
 
-## Файлы `__init__.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
+
+### Создание Pull Request 
 **1 Pull Request = 1 issue**
 
 Один Pull Request должен решать ровно одно issue.
 
 **Почему?** Потому что ревьюверу сложнее держать контекст нескольких задач в голове и переключаться между ними.
 
 
-## Размер Pull Request
+### Размер Pull Request
 Итоговый дифф PR не должен превышать +/- 600 измененных строк.
 
 Плохо ❌:
@@ -158,14 +160,15 @@ from some.absolute.path import foo, bar
 Также, большинству ревьюверов будет сложно воспринять такой объем изменений за один раз.
 
 
-## Пакетный менеджер
+## Тулинг
 
-[poetry](https://python-poetry.org) - менеджер зависимостей и сборщик пакетов 
+### Пакетный менеджер (poetry)
 
+[poetry](https://python-poetry.org) - менеджер зависимостей и сборщик пакетов 
 
-## Форматирование кода
 
-[black](https://black.readthedocs.io/en/stable/) - автоформаттер кода по PEP8
+### Форматирование кода (Black)
+[Black](https://black.readthedocs.io/en/stable/) - автоформаттер кода по PEP8
 
 Рекомендуемый конфиг в `pyproject.toml`:
 ```toml
@@ -192,6 +195,7 @@ exclude = '''
 ```
 
 
+### Форматирование импортов (isort)
 [isort](https://pycqa.github.io/isort/) - автоформаттер блока импортов
 
 Рекомендуемый конфиг в `pyproject.toml`:
@@ -209,6 +213,7 @@ lines_after_imports = 2
 ```
 
 
+### Линтер (flake8)
 [flake8](https://flake8.pycqa.org/en/latest/) - валидатор соответствия PEP8
 
 Рекомендуемый конфиг в `.flake8`:
@@ -223,7 +228,24 @@ per-file-ignores =
 ```
 
 
-## Pre-commit хуки
+### Тайп-чекер (mypy)
+
+[mypy](http://mypy.readthedocs.io) - чекер для статической типизации
+
+Рекомендуемый конфиг `mypy.ini`:
+
+```ini
+[mypy]
+ignore_missing_imports = True
+allow_untyped_globals = True
+
+[mypy-*.migrations.*]
+ignore_errors = True
+
+```
+
+
+### Pre-commit хуки (pre-commit)
 
 [pre-commit](https://pre-commit.com) - фреймворк для управления `pre-commit` хуками
 
@@ -250,20 +272,10 @@ repos:
 ```
 
 
-## Типизация
+## Прочее
 
-[mypy](http://mypy.readthedocs.io) - чекер для статической типизации
-
-
-Рекомендуемый конфиг `mypy.ini`:
-
-```ini
-[mypy]
-ignore_missing_imports = True
-allow_untyped_globals = True
-
-[mypy-*.migrations.*]
-ignore_errors = True
-
-```
+### Документация к REST API
+Рекомендуемый формат документации - [OpenAPI](https://www.openapis.org).
+Схема для OpenAPI должна генерироваться "на лету", чтобы обеспечивать клиентов API свежими изменениями.
 
+**Почему?** Потому что это один из распространенных форматов для документирования REST API, который вышел из Swagger. Данный формат документации поддерживается большим количеством клиентов (Swagger, Postman, Insomnia Designer и многие другие). Также, рукописная документация имеет свойство быстро устаревать, а документация, которая генерируется напрямую из кода позволяет не думать о постоянном обновлении документации.