В этой статье я познакомлю вас с руководством по стилю кода Python, которое также известно как PEP 8.
PEP расшифровывается как Python Enhancement Proposal и является руководством по стилю кода для Python. Это не строгий свод правил, а ориентир, которому разработчики Python должны следовать при написании кода.
PEP 8 определяет, как следует делать отступы в коде и какие соглашения об именовании являются предпочтительными. Он также описывает, как следует писать комментарии и что должно быть включено в код.
Важно следовать PEP 8, потому что так ваш код будет вам же самим легче читать и понимать. Это также облегчит понимание вашего кода другими разработчиками, что может помочь им более эффективно внести предложения по его улучшению.
Основные положения PEP 8
Форматирование
PEP 8 предлагает делать отступы в коде на 4 пробела. Это облегчает чтение кода и делает отступы четкими. Если вы не используете одинаковое количество пробелов, то отступ может быть трудно заметен. Это также помогает поддерживать чистоту кода, что облегчает поиск строк кода, которые вы хотите изменить.
Именование
Важно называть переменные и функции так, чтобы это имело смысл. Если вы используете случайное имя, то может быть трудно понять, что делает переменная или функция. Например, допустим, вы создаете программу на Python, которая использует цвета. Лучше назвать свою переменную color, а функцию make_green(). Это гораздо легче понять, чем случайное имя типа col или m_g()
Проставляйте пробелы так, будто вы пишите не код, а живой текст:
Кому понравится читать текст , когда знаки препинания отделены пробелом с двух сторон ?
Так же и в Python:
def make_greener(color: str, intensity: float) -> str:
x, y = y, x;
{k: v for k, v in zip(x, y)}
Несколько исключений:
def make_color(red: float = 0.0, green: float = 0.0, blue: float = 0.0) -> str:
def convert_to_bw(color: str, intensity=0.0) -> str:
Знак "равно" для указания стандартного значения после указания типа переменной - отделяется с двух сторон.
Без указания типа переменной - пробелом не отделяется.
Комментарии
Вы должны использовать комментарии только для объяснения того, что делает код, а не для описания того, что код должен делать. Например, допустим, вы пишете программу, которая возводит числа в квадрат. Вы можете написать такой комментарий к главному выражению программы - "умножает два числа друг на друга" (хоть это и так должно быть понятно из кода)
А вот чего вы определенно не должны писать, так это комментарий по типу "Результат этого кода равен 41".
В примере выше _map будет преобразован в юзер-friendly список, который будет выведен на экран; начинать список с нулевого элемента не считается странным почти что только у программистов, потому поясним, что добавили 1 к индексному значению именно для удобства пользователя.
Также не следует использовать комментарии к коду для объяснения назначения программы, для этого лучше использовать документацию.
docstrings
В дополнение к форматированию и именованию кода, PEP 8 описывает, что должно быть включено в код. Например, важно включать строки документации для функций и классов (docstring). docstring - это строка, которая описывает, что делает функция или класс, какие аргументы (если они есть) какого типа она принимает и что в итоге возвращает. Можно написать docstring, в котором говорится:
"""Создает синий круг радиусом n и рисует его на экране"""
а можно написать docstring, в котором говорится:
"""Вычисляет квадратный корень из числа n и возвращает его в виде строки"""
А вот пример из живого кода
Существует несколько основных стилей оформления docstring в Python, лично я использую Google docstring format - мне его гораздо удобнее и приятнее читать. Вот здесь можно узнать про разные форматы больше (SO, Eng).
В примере выше мы указываем всю необходимую информацию о функции:
- Args - Список аргументов, их описание и ожидаемый тип
- Returns - То, что функция возвращает
- Raises - Какие ошибки могут возникнуть во время работы функции и какой Error или Exception мы можем ожидать
Контекстные менеджеры
Контекстные менеджеры важны, потому что они обеспечивают способ самоочистки. Например, если у вас есть ресурс, который вам нужно открыть, вы можете использовать контекстный менеджер, чтобы убедиться, что ресурс всегда в результате будет закрыт.
Даже если произошел сбой или возникла ошибка, контекстный менеджер сначала закроет файл перед завершением работы - таким образом, вам не придется беспокоиться о том, чтобы закрывать файл самостоятельно.
Менеджеры контекста, это, абсолютно не только о файлах - с их помощью вы можете закрывать соединения с БД или делать необходимую очистку в своем собственном объекте. Мы посмотрим на то, как это делать, в одном из следующих постов.
В заключение
Сегодня мы поговорили о Python PEP 8 - руководстве по стилю кода Python. Надеюсь, что вы нашли эту статью полезной. Подписывайтесь на мой блог, если хотите быть в курсе дальнейших публикаций.
Спасибо за прочтение и хорошего дня!
