Как выстроить культуру оценки качества кода в команде

Оценка качества кода не чек-лист и не набор строгих обязательств. Это установленные внутри команды правила о создании кода, чтобы с ним было удобно работать ещё долгое время. В реальных проектах такие договорённости часто появляются из рабочих процессов: ревью, автоматических проверок, наблюдения за работой программ.

Культура оценки кода сама по себе не появится, её можно и нужно выстраивать из тех вещей, которые проверены и органически подходят команде. Обычно такие правила нужно постепенно выстраивать: через инструменты, договорённости и пример опытных разработчиков. Поэтому качество кода — это вопрос не только технологий, но и людей. 

Рассказываем, как проявляется культура оценки в компании и как с её помощью усиливаются итоговые результаты в команде.

Что такое качественный код

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

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

Методы и инструменты анализа кода

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

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

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

Статический и динамический анализ

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

Вот как это может выглядеть.

Почти в любой среде разработки IDE автоматически выдают предупреждения об ошибках. В нашем примере это PyCharm:

Если открыть описание ошибок, можно посмотреть, что именно не так:

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

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

Например, так работают автотесты:

Другой пример инструмента динамического анализа — система мониторинга:

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

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

Инструменты для автоматизации анализа

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

Вот несколько примеров инструментов статического анализа. Эти программы читают код, применяют к нему внутренние правила и выдают результат:

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

Примеры инструментов динамического анализа:

Code Review: значение и этапы

Code Review — это не критика одними разработчиками других, а способ разделить ответственность. Когда код смотрят несколько человек, вероятность пропустить ошибку сильно снижается.

Кроме поиска багов, ревью помогает выровнять стиль, обменяться знаниями и сформировать общее понимание проекта для прозрачности работы. Для новичков это один из самых быстрых способов расти.

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

Подготовка к Code Review

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

Чаще всего ревью проходит отдельный PR (pull request) — это запрос на добавление новой части кода в основную, уже проверенную и работающую программу. Небольшие изменения проверяются быстрее и качественнее. Если в одном PR есть и рефакторинг, и новые функции, и правки форматирования, его сложнее понять. Полезно заранее написать краткое описание для PR: что изменилось и почему. Это экономит время всей команде.

Что проверять в коде

В первую очередь нужно проверить корректность логики и возможные ошибки. Затем — читаемость и понятность для других разработчиков.

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

Этапы проведения Code Review

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

Такой порядок помогает не застревать в мелочах и видеть картину целиком.

Критерии качества кода

Критерии качества помогают объективно обсуждать код, а не спорить на уровне вкусов. Они задают общий язык для команды. Ниже — несколько распространённых критериев, которые подходят большинству команд.

Читаемость и структура

Читаемость — способность понять код без дополнительных объяснений. 

Хорошая структура помогает быстро находить нужные места и ориентироваться в проекте. Маленькие функции и логичная предсказуемая навигация снижают когнитивную нагрузку. Это особенно важно в больших кодовых базах.

Если код сложно читать, скорее всего, его будет сложно менять и развивать.

Императивность и декларативность

Императивный код описывает действия, декларативный — должный результат. Классический пример императивного кода — машинный язык, который объяснят машине инструкции максимально подробно. Декларативный стиль короче и понятнее, как язык программирования со встроенными методами и функциями. Мы просто говорим машине, что должно получиться в итоге, а нужные действия компьютер определяет сам.

Типизация данных и нейминги

Понятные имена переменных и функций — это хороший тон и одна из форм документации кода. Удобные названия уменьшают количество комментариев и вопросов. Если название требует пояснения — чаще всего оно неудачное.

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

# тип данных для переменной x — целое число
# присваиваем переменной значение 1000
# :int — аннотация типа 
x: int = 1000

# тип данных для переменной y — строка
# присваиваем переменной значение 'Привет, КОД'
# :str — аннотация типа
y: str = 'Привет, КОД!'

# тип данных для переменной z — словарь
# объявляем переменную и пока не присваиваем ей значение
# :dict — аннотация типа
z: dict

Code smells и техдолг

Code smells — это признаки проблем в коде. Даже если программа работает, в ней могут быть дублирование, слишком длинные функции, скрытые зависимости.

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

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

Преимущества и недостатки Code Review

Главное преимущество ревью — повышение качества и надёжности кода. Ошибки ловятся раньше, знания распределяются между всеми членами команды.

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

Метрики качества кода

Метрики помогают наблюдать за качеством в количественном выражении. Они полезны для анализа трендов, но полагаться только на показатели нельзя, потому что важно субъективное мнение профессиональных погруженных в проект разработчиков.

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

Цикломатическая сложность

Это количество независимых путей выполнения кода. На деле это означает количество возможных перемещений хода программы по ответвлениям внутри кода. За ответвления считаются управляющие конструкции:

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

Покрытие тестами

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

Покрытие показывает, какая часть кода выполняется во время тестов. Эта метрика помогает находить незащищённые участки. Но 100% покрытия не гарантирует отсутствие багов, потому что важно не только количество тестов, но и их качество.

Лучше иметь меньше тестов, но осмысленных и хорошо написанных, чем много, но формальных и поверхностных.

Поддерживаемость и безопасность

Поддерживаемость оценивает, насколько легко код менять без риска всё сломать. Это зависит от структуры и ясности логики.

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

Документация и стандарты кодирования

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

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

Что дальше

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