Чек-лист для инспекции кода в 2021 году

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

Введение

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

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

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

Контрольный список проверки кода

Я сделал это руководство в виде контрольного списка. В нем перечислен набор вопросов, которые вы должны задать о коде. Если ответ на любой из них не «да», вы должны оставить замечание о коде.

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

Этикет

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

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

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

Контрольный список вопросов:

• Является ли PR атомарным?
• Следует ли PR принципу единого беспокойства (Single Concern Principle)?
• Хорошо ли написаны сообщения о фиксации?

Идея:

Примените формат сообщения фиксации в команде. Например, вы можете попробовать gitmoji, где вы используете emoji в сообщениях о фиксации. Например, исправления ошибок должны начинаться с [FIX], или ? emoji, а новые функции должны начинаться с [FEAT] или ✨ emoji. Это действительно упрощает работу!

Функциональность и синтаксис

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

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

Перечень вопросов:

• Работает ли пиар?
• Добавляет ли новая функция ценность или это признак ползучести функции?
• Добавляет ли PR тест-кейсы для модифицированного кода?

Идея:

Наличие комплексных тестов в коде облегчает проверку того, что новая функциональность работает, и затрудняет PR ломать существующие вещи. Та часть кода, о которой идет речь, никогда не должна попадать в PR. Любой новый код должен иметь полный охват в модульных/функциональных тестах. Python поставляется с надежной платформой модульного тестирования, встроенной в сам язык. Вы должны использовать его в своей кодовой базе.

Дизайн

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

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

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

Чек-лист вопросов:

• Правильно ли спланирован и разработан код?
• Будет ли код хорошо работать с существующим кодом и не увеличит ли он дублирование?
• Хорошо ли организован код с точки зрения размещения компонентов?

Паттерны и идиомы

Python — очень зрелый язык. Он управляется на основе определенных философий, описанных как Дзен Питона (the Zen of Python). Эти философии породили множество условностей и идиом, которым, как ожидается, будет следовать новый кодекс.

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

Контрольный список вопросов:

• Соответствует ли код идиомам и кодовым шаблонам языка?
• Использует ли код языковые функции и стандартные библиотеки?

Идея:

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

Читабельность

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

Перечень вопросов:

• Является ли код ясным и кратким?
• Соответствует ли он PEP-8?
• Соблюдаются ли все языковые и проектные соглашения?
• Даны ли идентификаторам осмысленные и совместимые с руководством по стилю имена?

Идея:

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

Документация и ремонтопригодность

Следующее, что нужно проверить — это ремонтопригодность кода. Любой код, добавленный или измененный PR, должен быть написан для того, чтобы помочь кому-то, кроме оригинального автора, поддерживать его.

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

Чек-лист вопросов:

• Является ли код самодокументированным или хорошо документированным?
• Не является ли код запутанным и слишком сложным?
• Понятна ли взаимосвязь потока управления и компонентов?

Идея:

Sphinx — это генератор документации, который экспортирует красивую документацию из Python docstrings. Затем экспортированная документация может быть загружена в ReadTheDocs, популярный инструмент для размещения документов. Sphinx — одна из главных причин, почему я так люблю писать документацию.

Безопасность

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

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

Контрольный список вопросов:

• Свободен ли код от ошибок реализации, которые могут быть использованы?
• Были ли все новые зависимости проверены на наличие уязвимостей?

Идея:

Одним из известных анализаторов безопасности для Python является Bandit. Кроме того, если вы используете GitHub для размещения кода, вам обязательно следует прочитать это руководство по настройке обнаружения уязвимостей и Dependabot для вашей кодовой базы.

Как только вы настроите обнаружение уязвимостей на GitHub, вы получите такие уведомления:

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

Производительность, надежность и масштабируемость

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

Перечень вопросов:

1. Оптимизирован ли код с точки зрения временной и пространственной сложности?
2. Масштабируется ли он в соответствии с потребностью?
3. Есть ли у кода такие инструменты, как отчетность по метрикам и оповещение о сбоях?

Идея:

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

DeepSource

DeepSource — это автоматизированный инструмент проверки кода, который управляет сквозным процессом сканирования кода и автоматически делает запросы на вытягивание с исправлениями всякий раз, когда выдвигаются новые коммиты или новые запросы на вытягивание.

Настройка DeepSource для Python — это быстрый, простой и беспроблемный процесс. Просто добавьте файл .deepsource.toml в корень репозитория, и DeepSource немедленно заберет его для сканирования. Сканирование найдет область для улучшений в вашей кодовой базе, внесет эти улучшения и откроет запросы на вытягивание найденных изменений. Я был поражен простотой настройки и эффективностью их самодельного кодового движка.

Знаете ли вы, что DeepSource имеет честь быть в кураторском списке инструментов анализа исходного кода OWASP для Python?

Заключение

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

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

Я закончу эту статью с одной хорошей мыслью: «Хороший обзор кода улучшает не только код, но и программиста.»