Pre-commit — must have утилита любого проекта

Бывает смотришь на код и сразу видно, что код плохой. Признаков может быть множество:
— разные куски кода по-разному отформатированы
— импорты в файлах никак не структурированы
— используются вперемешку синтаксис старых и новых версий питона
— где-то видны зачатки использования типов, но не везде
— где-то docstring есть, где-то нет
Всё это характеризуется так: нет единого стиля в написании кода. Проблема становится особенно актуальной, когда над проектом трудится несколько разработчиков.

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

Для решения всех обозначенных проблем есть замечательная утилита — pre-commit. Один раз в конфиге прописываете, какие анализаторы кода нужно запускать, и далее при любом коммите они будут запускаться автоматически. С этого момента код будет опрятным и шелковистым. Вы просто не сможете сделать коммит, если у анализатора есть вопросики к коду.
#devfm #procode

Делаем код мягким и шелковистым

Мы уже говорили об утилите pre-commit, которая автоматизирует рутинный запуск анализаторов кода и не позволяет сделать коммит, пока проблемы не будут исправлены.

Теперь расскажем о тех утилитах, которые применяются в каждом нашем проекте:
— flake8 — статический анализатор кода с поддержкой очень большого количества плагинов
— black форматирует и приводит код в общему виду
— mypy проверяет аннотации типов
— reorder-python-imports единообразно организует импорты
— autoflake удаляет неиспользуемые импорты и переменные
— pyupgrade обновляет синтаксис до текущей версии python
— yesqa удаляет ненужные #noqa

Применение всех утилит с настройками по умолчанию скорее вредно, поэтому вот несколько советов:
— настройте в pre-commit опцию exclude — список каталогов, для которых не применять анализатор
— в flake8 настройте игнорирование особо душных замечаний
— в autoflake настройте автоматическое исправление замечаний
— при использовании mypy совместно с pre-commit нужно пользоваться специальной версией

Применение перечисленных утилит в командной работе облегчит проведение code review. Никто не будет тратить время на то, что может поправить машина.

Расскажите, если на практике используете другие анализаторы кода.
#devfm #procode

Зачем нужны юнит-тесты

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

На помощь приходят юнит-тесты. Это изолированные тесты, покрывающие одну функцию. Писать их следует вместе с самой функцией, над которой вы сейчас работаете или которую изменяете. Выгодное отличие тестов от отладки – накопительный эффект. Чем больше уже написано тестов, тем меньше область поиска ошибки. Упавший тест часто сразу локализует ошибку, указывая на функцию с багом или неожиданным поведением.

Правильные юнит-тесты экономят время разработки, так как практически полностью заменяют длительную отладку. При этом юнит-тесты пишутся быстро, необходимо лишь зафиксировать входные данные и ожидаемый выход. С ростом размера проекта время на отладку возрастает, а время на написание юнит-теста не изменяется.

Бонусом юнит-тесты улучшают код. Грязный код с большим количеством внешних зависямостей, со множеством задач в одной функции, десятками вложенных if, глобальными переменными и прочими плохими практиками тестировать сложно. В результате необходимость написать юнит-тест толкает разработчика на декомпозицию функции на более простые, которые легче покрыть тестами. Но эти же функции становится легче понять стороннему разработчику.

Занятная рабочая история про пользу юнит-тестов — в канале Борис опять. Рекомендуем.

Полезно вспомнить про антипаттерны тестирования ПО.
#devfm #procode

Доработать нельзя переписать

Где поставить запятую в заголовке?

Стратегия "Доработать нельзя, переписать" свойственна молодым и неопытным разработчикам. Проще выкинуть старый код и написать новый, хороший и правильный.

Более опытные разработчики скажут "Доработать, нельзя переписать". Они знают цену кода, который уже кто-то написал и отладил. Предыдущий автор уже через боль и страдания создал работающее решение. Костыли в этом коде появились не просто так.

Самые опытные понимают, что положение запятой зависит от многих факторов. Есть грань, когда надо взять и переписать. Есть грань, когда надо упереться и продолжать поддерживать старый код.

В классической статье Грабли, на которые не стоит наступать (оригинал) Джоел Спольски рассуждает о вопросе выше. Он вспоминает о браузере Netscape, который умер в результате переписывания. Одной из причин желания всё переписать Джоел видит сложность чтения кода. С этим тяжело не согласиться. Остальные детали в статье.

Наш опыт. При работе со старым проектом сопротивляйтесь желанию выкинуть и переписать. Безопасно переписывать можно, если вложения трудозатрат в проект меньше пары человеко-месяцев. Для более крупных проектов нужны вменяемые основания для выбрасывания имеющейся кодовой базы. Десять раз подумайте.

Мы уже рекомендовали другие статьи Спольски: Верблюды и резиновые уточки и закон дырявых абстракций.
#devfm #procode

Давай-давай, пиши документацию

На всех проектах мы стараемся адекватно подходить к документированию. "Адекватно" означает не кидаться в крайности, когда к каждой строчке начинается писанина, или, наоборот, смотришь на проект и не понимаешь, куда коней запрягать.

Для нас хорошо задукоментированный проект, с которым приятно работать, включает три части: докстринги, ридми и тесты.

Считаем, что в докстрингах должно быть описано назначение функций с пояснением каких-то особо хитрых моментов, описаны принимаемые и возвращаемые параметры. Мы используем гугл нотацию. Также в комплекте с докстрингами неразрывно идет аннотация типов. Это особенно важно, когда на входе какие-то сложные структуры данных. Целью является облегчение чтения кода.

Теперь о ридми. У нас на проектах ридми состоит из следующих блоков:
— Вводная часть, где тезисно указываем общее назначение сервиса. Если у сервиса чётко выраженное назначение, то описываем общий алгоритм работы.

— Установка и запуск. В этой части указываем набор команд, которые необходимо выполнить, чтобы запустить проект.
Подробность описания должна быть такая, чтобы при первом знакомстве с проектом разработчик скопировал из ридми команды и без матерных выражений запустил проект.

И, конечно, мы всё запускаем в докере. О важности докера у нас есть отдельный пост.

В этом же разделе также важно описать, как запускать тесты. Очень важно.

— Переменные окружения и опции. Сложный проект требует настройки, поэтому обязательно указываем набор переменных окружения, которые нужны в проекте, с описанием их назначения и дефолтными значениями.

— В разделе "другое" пишем о каких-то специфичных для проекта моментах. К таким особенностям может относится, например, накатывание миграций.

Последнее в нашем списке хорошо задокументированного проекта — тесты. Тесты являются самой актуальной документацией. В ридми можно забыть что-то поправить, а запуск тестов всегда показывает реальное поведение программы. Именно поэтому в ридми важно указывать, как запускать тесты.

Резюмируя, чем больше вы дадите информации о том, как запускать, как управлять проектом, какие у него есть особенности, тем лучше. Это облегчит вход любому разработчику. С увеличением числа проектов качественная документация становится критически важной. Во время разработки кажется: да всё понятно, как запускать эту штуку. А через пол года написанный вами проект будет выглядеть чужим и непонятным.

И ещё мысль по поводу документации:
Считаем вредным советом или требованием писать документацию в каких-то сторонних системах, таких как конфлюенс (да, порой и такое требуют). Практика показала, что поддержание документации в актуальном виде в стороннем сервисе, мягко говоря, не работает. Очень сложно убедить и даже заставить разработчика поддерживать доку где-то в сторонней приблуде. С ридми проще — можно писать, не отходя от кассы. И контролировать легче, проверяя изменение доки в merge request.
#devfm #procode

ООП на простых примерах

В 40-минутном видео аккуратно объясняют три кита объектно-ориентированного программирования. Примеры даны на TypeScript, но понятны любому разработчику. Автор аккуратно иллюстрирует необходимость ООП, рассказывает про инкапсуляцию, наследование и полиморфизм. Покрыты даже относительно сложные вещи вроде параметрического и ad-hoc полиморфизма.

На трёх китах ООП автор не заканчивает. Вторая половина ролика повествует о композиции и агрегации на примере автомобиля с двигателем и колёсами, об абстрактных классах и интерфейсах, и даже немного о дженериках. Завершает изложение реализация паттернов Dependency Injection и Singleton. При этом Singleton во многих случаях является антипаттерном и мы не рекомендуем его применять.

Обратите внимание, как автор умело использует IDE для автогенерации сеттеров и геттеров. Не забывайте, что IDE — ваш добрый друг, который много чего умеет.

Про нюансы getattr и setattr в питоне мы делали отдельные посты.

#sudo #youtube #procode

Делай нейминг как сеньор

Все мы знаем, что нужно правильно и понятно именовать переменные. Правильно, понятно – а это как?

Ребята написали отличную статью, где комплексно, с разных сторон подошли к вопросу нейминга.

На самом деле проработанный, качественный нейминг очень важен. Один раз где-то, что-то плохо назовешь, а через месяц-другой эти наименования просочатся в документацию, аналитику, тесты, внешние api.

Неправильно именование приводит к неправильному пониманию, а дальше – к некорректному использованию.

Чтобы детальнее разобраться, автор выделяет несколько распространенных проблем: слишком общие название, избыточные названия, названия без контекста, названия с некорректным переводом или калькой со своего языка, абстрактные названия. Каждая из проблем сопровождается примерами.

К решению проблемы автор также подходит комплексно, отталкиваясь от понимания предметной области и того, как выстроить работу с неймингом на уровне команды и продукта.

Заканчивается статья набором конкретных практических советов, которые можно брать и применять.

#procode

Вариантность типов

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

Простой пример: тип Natural является подтипом Integer и Positive. И все трое одновременно являются подтипами Real. А тип Prime является подтипом всех вышеперечисленных.

Есть у нас функция, которая в качестве параметра принимает на вход определённый тип данных. А можем ли мы передать в качестве параметра подтип или надтип исходного типа данных? За это как раз отвечает вариантность типов.

Контравариантность, ковариантность, инвариантность — в статье все эти замечательные термины рассматриваются на конкретных понятных примерах.

Также прочтение статьи позволит более глубокого понять принцип подстановки Барбары Лисков (LSP), который фигурирует в известной аббревиатуре soLid.

В конце рассматривается реализация вариантности в различных языках программирования –TypeScript, C#, Java, C++.

А на тему вариантности в python у Диджи было замечательное видео.

#procode

Приоритизация технического долга

Технический долг штука хитрая, сначала незаметная. Но в какой-то момент начинает влиять на производительность системы и эффективность разработки.
И вроде всё просто — бери и исправляй. Но когда система разрастается, а бизнес требует новый функционал, появляются вопросики. За что хвататься? Всё явно не успеем, но забивать нельзя, потихоньку нужно закрывать долги.

В статье автор размышляет о приоритизации технического долга. На практике сводится к тому, что нужно ответить на два вопроса:

— Если мы ничего не будем предпринимать, усугубится ли проблема, или всё в целом останется на прежнем уровне, или вообще всё будет двигаться в сторону улучшения?

— Проблема относится к той части системы, которая активно развивается и используется или находится просто на обслуживании?

Ответив по каждой проблеме на эти вопросы, можно более осознанно приоритизировать свой технический долг.

#procode

Асинхронное взаимодействие сервисов с применением Kafka

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

У нас были посты для более глубокого погружения в Kafka. Например, тут в одной статье рассказывают самые основы, в другой разбирают неочевидные проблемы, возникающие на практике.

#python #procode