PEP8 для Python — правила красивого кода

Гвидо ван Россум, создатель Python, предложил стандарты PEP8 еще в 2001 году. Эти рекомендации необязательно выполнять, но они помогут сделать код более читаемым и понятным для других разработчиков. В этой статье рассмотрим, когда и как применять правила.

Что такое стандарты PEP8 для языка Python

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

Для чего придуман PEP8?

Правила написания кода на python делают код понятнее. Гвидо ван Россум говорил: «Код читают чаще, чем пишут». Например, вы можете потратить час или день, чтобы написать код для входа пользователя, но возвращаться к нему будете много раз, и каждый раз придется вспоминать, как он работает.

Через пару дней легко забыть, что конкретно делает код, особенно если вы новичок. Но если следовать PEP 8 Python, всё будет понятно: правильные отступы, пробелы и структура помогут быстро разобраться.

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

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

Требования PEP8 по оформлению Python-кода

Единообразие, наглядность и информативность — это основа PEP8. Используйте правила, чтобы сделать код понятнее и чище.

Отступы

В Python внутренние блоки кода выделяют отступами, а не специальными разделителями. Размер отступа — четыре пробела, без табуляции:

if (expression_is_true):
do_this()
elif (other_expression_is_true):
do_that()
else:
do_something_else()

Максимальная длина строки

Аргументы функций переносят на следующую строку и выравнивают, если строка слишком длинная:

def long_func (arg_one, arg_two,
arg_three, arg_four)

def extra_long_function_name (
arg_one, arg_two, arg_three,
arg_four):
do_something()

Некоторые редакторы при переносе строки добавляют спецсимвол, поэтому вместо стандартных 80 символов максимальная длина строки в PEP8 — 79. Комментарии и документация — 72 символа.

Максимальную длину строки разрешено увеличить до 99 символов, если код со стандартной длиной в 79 символов сложно прочитать.

Пустые строки

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

do_stuff()
do_similar_stuff()

do_different_stuff()

do_something_else_entirely()

Правила выбора имен

По названию переменной или функции сразу понятно, зачем они нужны. Например, в first_name лежит имя, а calculate_employee_salary() считает зарплату сотрудника.
Старайтесь использовать полные названия. Их проще читать, а сокращения понять труднее:

# Правильно

first_name = ‘Ivan’
last_name = ‘Ivanov’

def plus_one (x):
return x + 1

# Неправильно

fnm = ‘Ivan’
lnm = ‘Ivanov’

# Plus 1? Phase 1? Point 1?
def p1 (x):
return x + 1

Составили таблицу с некоторыми популярными стилями именования переменных в Python и советами, когда их использовать:

Проверка истинности без знаков равенства

Условия с булевыми значениями проверяются без оператора эквивалентности (==):

# Правильно

if this_is_true:
do_something()

if not this_is_false:
do_something_else()

# Неправильно

if this_is_true == True:
do_something()

if this_is_false == False:
do_something_else()
Оператор is / is not помогает сравнивать с None:

if connection is None:
print_error_message()

if user is not None:
get_user_data()

Пустой массив, список, словарь или строка — это False. С содержимым — уже True:

first_name = ‘’

if not first_name:
do_something () # выполнится
colors = [‘red’]

if colors:
do_something_else() # выполнится

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

Хороший комментарий — полезный комментарий. Пишите просто и понятно, обновляйте комментарии, если код меняется. Рекомендации PEP8:

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

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

# Returns a filled UserData object for the current user ID if user exists, None otherwise. Assumes database connection is already open
#
# TODO: very poor performance, rewrite it!

def get_user_data (db_connection, user_id)

Старайтесь реже оставлять внутренние комментарии. Они не должны объяснять очевидные вещи и затруднять чтение кода. Отделяйте их от текста как минимум двумя пробелами и начинайте с # и пробела:

# Правильно

first_name = ‘Ivan’ # test user, shouldn’t show up in prod

# Неправильно
first_name = ‘Ivan’ # first name

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

“””Run the provided database request. Scalar only!
For everything else, use db_query().
“””
В однострочных комментариях открывающие и закрывающие “ ” ” — на той же строке:
“””Flush buffer and close the file”””

Разработчику на любом языке нужно постоянно развиваться и совершенствовать навыки, чтобы оставаться востребованным специалистом. А вот основы можно узнать и отработать на курсе Skypro «Python-разработчик». Программу составили практикующие разработчики, они же ведут уроки и объясняют всё простым и доступным языком. Так что освоить профессию на уровне уверенного новичка и найти работу можно через несколько месяцев с начала учебы.

Выражения и инструкции

Стандартная кодировка для Python 3 — UTF-8. В Python 2 — ASCII, которая не поддерживает кириллицу. Используйте Windows 1251 или аналоги:

# coding: cp1251
print (“Текст кириллицей”)

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

import os
from math import pi, sin

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

# Правильно

if this_is_true
and that_is_true
and something_else_is_true:
do_stuff();
do_other_stuff();

# Допустимо
if file_position < 0: file_position = 0 # file system quirk

Использование запятых

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

# Правильно

TEST_USERS = (‘ivanov_i’, )

TEST_ACCOUNT_IDS = [

‘123’,

‘456’,

]

# Неправильно

TEST_USERS = ‘ivanov_i’,

TEST_ACCOUNT_IDS = [‘123’, ‘456’, ]

Кодировка исходного файла

В Python 3 по умолчанию используют UTF-8 — универсальную кодировку, которая поддерживает кириллицу, спецсимволы и эмодзи. Благодаря этому текст в разных системах отображается одинаково.

Прописывать кодировку в начале нужно, если в файле есть не-ASCII символы — например, комментарии на русском.

# coding: utf-8

Кавычки литера строки

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

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

Пробелы в выражениях и инструкциях

Пишите типы аргументов и возвращаемого значения через двоеточие (:), а стрелку (->) окружайте пробелами:

def sum(a: int, b: int) -> int:
return a + b

Для типов переменных вставляйте один пробел после двоеточия. Знак присваивания окружайте пробелами с обеих сторон:

# Правильно

user_count: int

class UserData:
first_name: str = ‘replace_me’
login_and_password_hash: Tuple[str, str]

# Неправильно

user_count:int
user_count : int

class UserData:
first_name: str=’’

Рекомендации по программированию

Указывайте специальный комментарий, чтобы автоматические проверки игнорировали файл. Это правило действует, если в проекте используете любые другие виды аннотаций:

# type: ignore

По умолчанию Python игнорирует аннотации, когда выполняет программу. Проверить типы автоматически не получится, нужно использовать дополнительные инструменты — например, линтеры.

Другие рекомендации, на которые стоит обратить внимание:

1. Используйте стандартную библиотеку, а не конкретную имплементацию (PyPy, CPython и т. д.).
2. Реализуйте все операторы (__eq__, __ne__, __lt__, __le__, __gt__, __ge__), чтобы сравнить элементы.
3. Определяйте функции ключевым словом def, а не знаком равенства: равенство оставляйте для лямбд.
4. Наследуйте исключения от Exception вместо BaseException.
5. Сохраняйте стек вызовов, когда проверяете цепочки исключений.
6. Обрабатывайте конкретное исключение: слишком широкое условие или пустой оператор except поймает больше, чем нужно.
7. Минимизируйте количество кода в try-блоке: в длинных условиях легче потеряться или пропустить ошибку.
8. Очищайте локальные ресурсы с помощью with или try/finally.
9. Вызывайте методы в менеджерах контекста явно. Исключение — резерв или возврат ресурса.
10. Возвращайте единообразные значения: либо везде пустой return, либо везде результат или None.
11. Проверяйте префиксы и суффиксы строк с помощью .startswith() и .endswith().
12. Сравнивайте типы объектов через isinstance().
13. Избегайте строковых литералов с пробельными символами в конце: некоторые редакторы и модули их обрежут.

Как проверить код на соответствие стандартам PEP8

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

1. Среды разработки, например PyCharm.
2. Pylint — для статического анализа и проверки стиля.
3. Flake8 — для проверки стиля.

Pylint, Flake8 и другие инструменты можно найти в разделе Python Code Quality Authority на «Гитхабе».

Изучайте Python на онлайн-курсе от Skypro «Python-разработчик». Программа рассчитана на новичков без опыта программирования и технического образования. Курс проходит в формате записанных коротких видеолекций. Будет много проверочных заданий и мастер-классов. В конце каждой недели — живая встреча с экспертами в разработке для ответов на вопросы и разбора домашек.

Когда можно проигнорировать соблюдение стандартов

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

В проектах без единого стиля — договоритесь с командой и берите PEP8.

Коротко о главном

• Пишите единообразный код: его приятнее читать и легче воспринимать. PEP8 — стилевой стандарт сообщества.
• Выравнивайте блоки кода и отделяйте логические секции пустыми строками.
• Выбирайте понятные и однозначные имена для объектов.
• Добавляйте полезные комментарии. Обновляйте их, когда код меняется.
• Обрабатывайте исключения с узкими и краткими условиями.
• Берите автоматические инструменты проверки.
• Игнорируйте стандарты, если их соблюдение ухудшит код.