Python гайдлайн Evrone для унифицированной разработки

Программируя на Python, разработчики должны учитывать множество деталей. Подходы и практики разнятся от компании к компании и от команды к команде. В Evrone мы создали собственную подборку гайдлайнов, чтобы привести к общему знаменателю корпоративные правила написания кода на Python.

Как гайдлайны Evrone могут помочь вам

Многие разработчики на Python часто оказываются в сходных ситуациях, для которых существуют общие удобные и универсальные решения. В таких случаях наши гайды подскажут, как следует действовать.

О коде

В разделе «О коде» описываются определенные принципы, следуя которым вы сможете написать код:

• простой и читабельный;
• поддерживаемый;
• с простыми и очевидными конструкциями.

Мы создали список условий для достижения этих трёх требований: атомарность операций, логические блоки, размеры методов, функций и модулей, докстринги, файлы __init__.py и импорты.

Например, если мы говорим об импорте, то рекомендуемый метод импорта — absolute.

Плохо ❌ :

# spam.py
from . import foo, bar

Хорошо ✅ :

# spam.py
from some.absolute.path import foo, bar

Почему мы его рекомендуем? Потому что абсолютный импорт явно определяет местоположение (путь) импортируемого модуля. При относительном импорте всегда нужно помнить путь и вычислять в уме расположение модулей foo.py, bar.py относительно spam.py

О пул-реквестах

В следующем разделе описаны методы, связанные с pull request. Как ни странно, не все разработчики знают, как создавать такие запросы или как их рецензировать. Часто в пул-реквестах предлагается много правок (от 1000 строк и более). В этом случае правки трудно читать, из-за чего, в свою очередь, труднее понять, как работает код или как в нём реализована та или иная функция.

Ещё одна очень распространённая проблема, с которой сталкиваются многие тимлиды: программисты часто смешивают в пул-реквестах несколько задач. Запрос получается слишком большим и создаёт путаницу. Мы решили формализовать решения, чтобы не вести бесконечные разговоры на эту тему с каждым по отдельности. Так в руководстве появился раздел «О пул-реквестах».

Об инструментарии

В разных проектах нам приходится использовать разные инструменты. Например, иногда мы не можем внедрить некоторые регулярно используемые инструменты в проект, потому что тот слишком велик. Что касается линтеров (инструментов, которые помогают улучшить код), то их необходимо подключать в начале проекта. Нельзя подключать линтеры в середине или в конце проекта, так как накопится слишком много правок, и ни у кого не найдется огромного количества времени, чтобы разобраться с ними в один присест. К тому же такие изменения существенно удлиняют срок работы и удорожают проект, необходимость чего сложно обосновать для клиента.

Поэтому мы добавили раздел «О тулинге» (о тестах, менеджерах пакетов, форматировании кода и т. д.). Какую проблему это решает? Все пишут код по-разному. Каждый разработчик на Python придерживается своего стиля. Поэтому, чтобы не спорить об индивидуальных предпочтениях, применяются специальные инструменты, которые переписывают весь код согласно определённым правилам. Мы предлагаем использовать ряд очень удобных инструментов.

Например, для тестирования кода мы советуем использовать фреймворк pytest. Рекомендуемая конфигурация в pytest.ini:

[pytest]
DJANGO_SETTINGS_MODULE = settings.local
python_files = tests.py test_*.py *_tests.py

Мы используем poetry для управления зависимостями и сборки пакетов, а black — для форматирования кода в соответствии с PEP8.

Рекомендуемый конфиг в pyproject.toml:

[tool.black]
line-length = 100
target-version = ['py38']
exclude = '''
(
  \.eggs
  |\.git
  |\.hg
  |\.mypy_cache
  |\.nox
  |\.tox
  |\.venv
  |_build
  |buck-out
  |build
  |dist
)
'''

Прочее

Ещё одна проблема, которую мы обнаружили: некоторые не знают, как документировать то, что они сделали. В разделе «Прочее» мы предлагаем использовать один из самых современных форматов документации — OpenAPI. В проектах, над которыми работаем, мы стараемся внедрять документацию OpenAPI, чтобы всё можно было генерировать «на лету». Это очень удобный, унифицированный инструмент, который позволяет привести спецификацию к единому формату.

Этот формат документации поддерживается большим количеством клиентов (Swagger, Postman, Insomnia Designer и др.). Кроме того, рукописная документация имеет тенденцию быстро устаревать, а документация, которая генерируется непосредственно из кода, позволяет не думать постоянно об её обновлении.

Заключение

Наши гайдлайны помогают решить распространённые проблемы, с которыми сталкиваются программисты при написании кода на Python.

Гайдлайны полезны:

• На этапе найма разработчиков. Ещё до начала работы они могут познакомиться с принципами, по которым пишется наш код.
• Когда разработчик присоединяется к новому проекту, он придерживается принципов, изложенных в гайдах, в своей работе.
• Даже если разработчик уже некоторое время работает в проекте, тимлид может прислать ему ссылки на эти гайды, если возникнут какие-либо трудности.
• Как известно, программистам всегда интересно видеть принципы, по которым пишется код в другой компании. Так что можно сказать, что, публикуя эти рекомендации, мы позволяем заглянуть на внутреннюю кухню нашей компании.

Мы инициативны и понимаем, что нравится и требуется разработчикам. Подтверждение этому — наша работа над open source проектами, а также то, что мы ежемесячно выбираем несколько OSS-проектов и оказываем им спонсорскую поддержку. Если вам нужно разработать open-source-решение или вы ищете команду профессионалов, которые выполнят проект с нуля, свяжитесь с нами через форму ниже.