Гвидо ван Россум, создатель 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 и советами, когда их использовать:
Тип | Рекомендация | Примеры |
Функция | Одно или несколько слов в нижнем регистре, нижние подчеркивания для улучшения читаемости (snake case) | function, add_one |
Переменная | Одна буква, слово или несколько слов в нижнем регистре, нижние подчеркивания | x, connection, first_name |
Класс | Одно или несколько слов с большой буквы без пробелов (camel case) | Image, UserData |
Метод | Одно или несколько слов в нижнем регистре, нижние подчеркивания | draw(), get_user_data() |
Константа | Одна буква, слово или несколько слов в верхнем регистре, нижние подчеркивания | PI, MAX_CONNECTIONS |
Модуль | Короткое слово или слова в нижнем регистре, нижние подчеркивания | module.py, user_data.py |
Пакет | Короткое слово или слова в нижнем регистре без подчеркиваний | package, userdata |
Проверка истинности без знаков равенства
Условия с булевыми значениями проверяются без оператора эквивалентности (==):
# Правильно 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:
- Пишите полные предложения с заглавной буквы, если это не название.
- Ставьте два пробела после точки в комментариях, кроме последнего предложения.
- Пишите на английском, если читатели не знают ваш язык.
Блочный комментарий объясняет следующий за ним участок кода. Выравнивайте комментарии на том же уровне и начинайте каждую строку с # и пробела. Параграфы в блочных комментариях разделяют строкой с одной #:
# 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 игнорирует аннотации, когда выполняет программу. Проверить типы автоматически не получится, нужно использовать дополнительные инструменты — например, линтеры.
Другие рекомендации, на которые стоит обратить внимание:
- Используйте стандартную библиотеку, а не конкретную имплементацию (PyPy, CPython и т. д.).
- Реализуйте все операторы (__eq__, __ne__, __lt__, __le__, __gt__, __ge__), чтобы сравнить элементы.
- Определяйте функции ключевым словом def, а не знаком равенства: равенство оставляйте для лямбд.
- Наследуйте исключения от Exception вместо BaseException.
- Сохраняйте стек вызовов, когда проверяете цепочки исключений.
- Обрабатывайте конкретное исключение: слишком широкое условие или пустой оператор except поймает больше, чем нужно.
- Минимизируйте количество кода в try-блоке: в длинных условиях легче потеряться или пропустить ошибку.
- Очищайте локальные ресурсы с помощью with или try/finally.
- Вызывайте методы в менеджерах контекста явно. Исключение — резерв или возврат ресурса.
- Возвращайте единообразные значения: либо везде пустой return, либо везде результат или None.
- Проверяйте префиксы и суффиксы строк с помощью .startswith() и .endswith().
- Сравнивайте типы объектов через isinstance().
- Избегайте строковых литералов с пробельными символами в конце: некоторые редакторы и модули их обрежут.
Как проверить код на соответствие стандартам PEP8
Проверять проекты вручную долго. И можно ошибиться. Используйте готовые инструменты:
- Среды разработки, например PyCharm.
- Pylint — для статического анализа и проверки стиля.
- Flake8 — для проверки стиля.
Pylint, Flake8 и другие инструменты можно найти в разделе Python Code Quality Authority на «Гитхабе».
Изучайте Python на онлайн-курсе от Skypro «Python-разработчик». Программа рассчитана на новичков без опыта программирования и технического образования. Курс проходит в формате записанных коротких видеолекций. Будет много проверочных заданий и мастер-классов. В конце каждой недели — живая встреча с экспертами в разработке для ответов на вопросы и разбора домашек.
Когда можно проигнорировать соблюдение стандартов
Главное правило: единообразный код понятнее читается. Но PEP8 не применяют, если проект приватный, уже использует другой стиль или его разрабатывали под старые версии Python. Для публичных библиотек PEP8 обязателен.
В проектах без единого стиля — договоритесь с командой и берите PEP8.
Коротко о главном
- Пишите единообразный код: его приятнее читать и легче воспринимать. PEP8 — стилевой стандарт сообщества.
- Выравнивайте блоки кода и отделяйте логические секции пустыми строками.
- Выбирайте понятные и однозначные имена для объектов.
- Добавляйте полезные комментарии. Обновляйте их, когда код меняется.
- Обрабатывайте исключения с узкими и краткими условиями.
- Берите автоматические инструменты проверки.
- Игнорируйте стандарты, если их соблюдение ухудшит код.
Добавить комментарий