Как написать красивый код на Python с помощью PEP 8

Оглавление

Смотрите сейчас, к этому уроку прилагается соответствующий видеокурс, созданный командой Real Python. Посмотрите его вместе с письменным руководством, чтобы углубить свое понимание: Написание красивого кода на Python с помощью PEP 8

PEP 8, иногда пишущийся как PEP8 или PEP-8, является официальным руководством по стилю кода на Python. PEP 8 содержит рекомендации по соглашениям об именовании, компоновке кода и другим рекомендациям. Гвидо ван Россум, Барри Уоршоу и Алисса Коглан написали его в 2001 году, уделяя особое внимание повышению читаемости и согласованности кода. Придерживаясь PEP 8, вы гарантируете, что ваш код на Python удобочитаем и сопровождаем, что помогает в совместной работе и профессиональном развитии.

К концу этого урока вы поймете, что:

  • PEP 8 - это руководство по написанию чистого, читабельного и последовательного кода на Python.
  • PEP 8 по-прежнему актуален в современной разработке на Python.
  • Всем разработчикам Python рекомендуется использовать , следующий за PEP 8.
  • Python использует регистр snake для имен переменных — слова в нижнем регистре, разделенные символами подчеркивания.
  • В именах функций Python также следует использовать змеиный регистр.
  • Имена классов в Python используют регистр camel, причем каждое слово начинается с заглавной буквы.

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

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

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

<отметить класс="marker-highlight"> Пройдите тест: Проверьте свои знания с помощью нашего интерактивного теста “Как писать красивый код на Python с помощью PEP 8”. По завершении вы получите оценку, которая поможет вам отслеживать прогресс в обучении:

<время работы/> How to Write Beautiful Python Code With PEP 8

Интерактивная викторина

Как написать красивый код на Python с помощью PEP 8

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

Зачем нам нужен PEP 8

“Читабельность имеет значение”.

— Дзен в Python

PEP 8 существует для улучшения читаемости кода на Python. Но почему читаемость так важна? Почему написание читаемого кода является одним из руководящих принципов языка Python, согласно Дзен Python?

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

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

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

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

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

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

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

Соглашения об именовании

“Явное лучше неявного”.

— Дзен Python

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

Одно из предложений - никогда не использовать l, O, или I однобуквенные имена, поскольку их можно принять за 1 и 0, в зависимости от того, какой шрифт использует программист.

Например, рассмотрим приведенный ниже код, в котором одной букве присваивается значение 2 O:

O = 2  # ❌ Not recommended


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

Стили именования

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

Type Naming Convention Examples
Function Use a lowercase word or words. Separate words by underscores to improve readability. This style is called snake case. function, python_function
Variable Use a lowercase single letter, word, or words. Separate words with underscores to improve readability. x, var, python_variable
Class Start each word with a capital letter. Don’t separate words with underscores. This style is called camel case or Pascal case. Model, PythonClass
Method Use a lowercase word or words. Separate words with underscores to improve readability (snake case). class_method, method
Constant Use an uppercase single letter, word, or words. Separate words with underscores to improve readability. CONSTANT, PYTHON_CONSTANT, PYTHON_LONG_CONSTANT
Module Use a short, lowercase word or words. Separate words with underscores to improve readability. module.py, python_module.py
Package Use a short, lowercase word or words. Don’t separate words with underscores. package, pythonpackage

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

Как правильно выбирать имена

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

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

❌ Not recommended
>>> x = "John Smith"
>>> y, z = x.split()
>>> print(f"{z}, {y}")
'Smith, John'

Это сработает, но вам придется следить за тем, что представляют собой x, y, и z. Это также может сбить с толку сотрудников. Гораздо более понятным выбором имен было бы что-то вроде этого:

✅ Recommended
>>> name = "John Smith"
>>> first_name, last_name = name.split()
>>> print(f"{last_name}, {first_name}")
'Smith, John'

Аналогичным образом, чтобы сократить количество вводимых данных, может возникнуть соблазн использовать сокращения при выборе имен. В приведенном ниже примере вы определили функцию db(), которая принимает единственный аргумент x и удваивает его:

❌ Not recommended
def db(x):
    return x * 2

На первый взгляд, это может показаться разумным выбором. Название db() может быть сокращением от double. Но представьте, что вы вернетесь к этому коду через несколько дней. Возможно, вы забыли, чего пытались добиться с помощью этой функции, и из-за этого будет сложно догадаться, как вы ее сократили.

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

✅ Recommended
def multiply_by_two(x):
    return x * 2

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

Расположение кода

“Красивое лучше уродливого”.

— Дзен в Python

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

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

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

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

class FirstClass:
    pass


class SecondClass:
    pass


def top_level_function():
    return None


Таким образом, в PEP 8 предлагается окружать функции верхнего уровня и определения классов двумя пустыми строками.

Разделите определения методов внутри классов одной пустой строкой. Все методы внутри класса связаны друг с другом. Рекомендуется оставлять между ними только одну строку:

class ClassWithMethods:
    def first_method(self):
        return None

    def second_method(self):
        return None


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

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

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

def calculate_variance(numbers):
    sum_numbers = 0
    for number in numbers:
        sum_numbers = sum_numbers + number
    mean = sum_numbers / len(numbers)

    sum_squares = 0
    for number in numbers:
        sum_squares = sum_squares + number**2
    mean_squares = sum_squares / len(numbers)

    return mean_squares - mean**2


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

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

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

В PEP 8 предлагается ограничить количество строк 79 символами. Это позволяет открывать несколько файлов рядом друг с другом, избегая при этом переноса строк.

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

Python примет продолжение строки, если код содержится в круглых скобках или фигурных скобочках:

def function(arg_one, arg_two,
             arg_three, arg_four):
    return arg_one


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

Если невозможно использовать подразумеваемое продолжение, то вместо этого вы можете использовать обратную косую черту (\) для разрыва строк:

from package import example1, \
    example2, example3


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

Если вам нужно разбить строку вокруг двоичных операторов, таких как + и *, то вам следует сделать это перед оператором. Это правило основано на математике. Математики сходятся во мнении, что разбиение перед двоичными операторами улучшает читаемость. Сравните следующие два примера.

Ниже приведен пример разбиения перед двоичным оператором:

✅ Recommended
total = (first_variable
         + second_variable
         - third_variable)

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

Теперь, вот пример разбиения после двоичного оператора:

❌ Not recommended
total = (first_variable +
         second_variable -
         third_variable)

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

Разбиение перед двоичными операторами позволяет получить более читаемый код, поэтому PEP 8 поощряет это. Код, который последовательно разбивается после двоичного оператора, по-прежнему соответствует PEP 8. Однако рекомендуется прерываться перед двоичным оператором.

Отступ

“Должен быть один — и желательно только один — очевидный способ сделать это”.

— Дзен Python

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

Рассмотрим следующий пример:

x = 3
if x > 5:
    print("x is larger than 5")


Вызов функции print() с отступом сообщает Python, что он должен выполнить эту строку только в том случае, если оператор if возвращает True. Тот же самый отступ применяется для указания Python, какой код следует выполнять при вызове функции или какой код принадлежит данному классу.

Основные правила оформления отступов, изложенные в PEP 8, следующие:

  • Используйте четыре последовательных пробела для обозначения отступа.
  • Предпочитайте пробелы символам табуляции.

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

Табуляция против пробелов

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

Python 3 не допускает смешивания табуляций и пробелов. Напишите следующий код и обязательно используйте пробелы там, где указано точкой (·), и символ табуляции там, где вы можете увидеть символ ():

mixed_indentation.py
 1def mixed_indentation(greet=True):
 2····if greet:
 3········print("Hello")
 4⇥   print("World")  # Indented with a tab.
 5
 6mixed_indentation()

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

Вы также можете скачать этот файл mixed_indentation.py:

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

Если вы используете Python 3 и запускаете код, в котором смешиваются табуляции и пробелы, то вы получите сообщение об ошибке:

$ python mixed_indentation.py
  File "./mixed_indentation.py", line 4
    print("World")  # Indented with a tab.
TabError: inconsistent use of tabs and spaces in indentation


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

Примечание: Устаревший Python 2 не выдаст ошибку, если вы смешаете табуляцию и пробелы. Это может привести к неоднозначным ситуациям в зависимости от того, как текстовый редактор интерпретирует символ табуляции.

Если вам интересно попробовать это, то вы можете установить версию Python 2 с помощью pyenv. Если вы запускаете mixed_indentation.py с помощью Python 2, то вы не увидите сообщение об ошибке, если не воспользуетесь параметром -t или -tt.

В PEP 8 рекомендуется всегда использовать четыре последовательных пробела для обозначения отступа.

Отступы после переносов строк

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

  1. Выравнивание по начальному разделителю
  2. Отступ для зависания

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

def function(arg_one, arg_two,
             arg_three, arg_four):
    return arg_one


Иногда вы можете обнаружить, что четыре пробела точно совпадают с начальным разделителем. Если вам интересно, как PEP 8 предлагает разрешить эти проблемы, вы можете развернуть раздел, который можно сворачивать, ниже:

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

x = 5
if (x > 3 and
    x < 10):
    print(x)


В PEP 8 нет строгой позиции относительно того, как справиться с этой ситуацией, но в нем предусмотрены две альтернативы, которые помогут улучшить читаемость.

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

x = 5
if (x > 3 and
    x < 10):
    # Both conditions satisfied
    print(x)


Комментарий визуально отделяет многострочный оператор if от блока кода с отступом.

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

x = 5
if (x > 3 and
        x < 10):
    print(x)


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

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

var = function(
    arg_one, arg_two,
    arg_three, arg_four)


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

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

❌ Not recommended
var = function(arg_one, arg_two,
    arg_three, arg_four)

Этот пример не соответствует требованиям PEP 8, поскольку вы помещаете arg_one и arg_two в первую строку рядом с открывающими круглыми скобками.

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

❌ Not recommended
def function(
    arg_one, arg_two,
    arg_three, arg_four):
    return arg_one

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

✅ Recommended
def function(
        arg_one, arg_two,
        arg_three, arg_four):
    return arg_one

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

Как показано выше, есть два способа сделать это:

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

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

Куда ставить закрывающую скобку

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

В PEP 8 предусмотрены два варианта расположения закрывающей скобки в подразумеваемых продолжениях строк:

  • Соедините закрывающую скобку с первым символом предыдущей строки, который не является пробельным:

    list_of_numbers = [
        1, 2, 3,
        4, 5, 6,
        7, 8, 9
        ]
    
  • Соедините закрывающую скобку с первым символом строки, с которой начинается построение:

    list_of_numbers = [
        1, 2, 3,
        4, 5, 6,
        7, 8, 9
    ]
    
    
    

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

Комментарии

“Если реализацию трудно объяснить, это плохая идея”.

— Дзен Python

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

Вот несколько ключевых моментов, которые следует помнить при добавлении комментариев к вашему коду:

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

Учитывая эти ключевые моменты, пришло время рассмотреть рекомендации ОПТОСОЗ 8, касающиеся комментариев, в деталях.

Блокировать комментарии

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

В PEP 8 предусмотрены следующие правила написания комментариев к блокам:

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

Вот комментарий к блоку, объясняющий функцию цикла for. Обратите внимание, что предложение переносится на новую строку, чтобы сохранить ограничение по длине строки в 79 символов:

for number in range(0, 10):
    # Loop over `number` ten times and print out the value of `number`
    # followed by a newline character.
    print(number, "\n")


Иногда, если код очень технический, то в комментарии к блоку необходимо использовать более одного абзаца:

# Calculate the solution to a quadratic equation using the quadratic
# formula.
#
# A quadratic equation has the following form:
# ax**2 + bx + c = 0
#
# There are always two solutions to a quadratic equation, x_1 and x_2.
x_1 = (-b + (b**2 - 4 * a * c) ** (1 / 2)) / (2 * a)
x_2 = (-b - (b**2 - 4 * a * c) ** (1 / 2)) / (2 * a)


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

Встроенные комментарии

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

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

Ниже приведен пример встроенного комментария:

x = 5  # This is an inline comment


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

❌ Not recommended
x = "John Smith"  # Student Name

Здесь встроенный комментарий дает дополнительную информацию. Однако использование x в качестве имени переменной для имени пользователя - плохая практика. Нет необходимости в встроенном комментарии, если вы переименуете свою переменную:

✅ Recommended
student_name = "John Smith"

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

❌ Not recommended
empty_list = []  # Initialize empty list

x = 5
x = x * 5  # Multiply x by 5

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

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

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

Строки документации

Строки документации, или строки документации - это строки, заключенные в тройные двойные кавычки (""") или тройные одинарные кавычки ('''), которые отображаются в первой строке любой функции, класса, метода или модуля:

documented_module.py
 1"""This is a docstring."""
 2
 3# ...

Вы используете строки документации для объяснения и документирования определенного блока кода. Они являются важной частью Python, и вы можете получить доступ к строке документации объекта, используя его атрибут .__doc__ или функцию help():

>>> import documented_module

>>> documented_module.__doc__
'This is a docstring.'

>>> help(documented_module)
Help on module documented_module:

NAME
    documented_module - This is a docstring.

FILE
    ./documented_module.py


В то время как в PEP 8 упоминаются строки документации, они представляют собой достаточно обширную тему, поэтому существует отдельный документ, PEP 257, который полностью посвящен к строкам документации.

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

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

def adder(a, b):
    """Add a to b."""
    return a + b


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

Затем вы можете использовать больше текста для документирования объекта code. В этой части строки документации вы также можете включить описание аргументов и возвращаемого значения.

Наконец, вы должны поместить три кавычки, которые завершают многострочную строку документации, в отдельную строку:

def quadratic(a, b, c):
    """Solve quadratic equation via the quadratic formula.

    A quadratic equation has the following form:
    ax**2 + bx + c = 0

    There always two solutions to a quadratic equation: x_1 & x_2.
    """
    x_1 = (-b + (b**2 - 4 * a * c) ** (1 / 2)) / (2 * a)
    x_2 = (-b - (b**2 - 4 * a * c) ** (1 / 2)) / (2 * a)

    return x_1, x_2


Более подробное руководство по документированию кода на Python, в котором также рассматриваются различные стили строк документации, смотрите в разделе Документирование кода на Python: полное руководство.

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

“Разреженность лучше, чем плотность”.

— Дзен Python

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

Пробелы вокруг двоичных Операторов

Для лучшей читаемости в соответствии с PEP 8, следующие двоичные операторы заключите в одинарный пробел с обеих сторон:

Когда вы используете знак равенства (=) для присвоения значения по умолчанию аргументу, не заключайте его в пробелы:

# ✅ Recommended
def function(default_parameter=5):
    # ...


# ❌ Not recommended
def function(default_parameter = 5):
    # ...


Отсутствие пробелов при указании значений аргументов по умолчанию позволяет сделать определения функций и методов более краткими.

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

# ✅ Recommended
y = x**2 + 5
z = (x+y) * (x-y)

# ❌ Not recommended
y = x ** 2 + 5
z = (x + y) * (x - y)


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

Вы также можете применить это к if операторам, в которых есть несколько условий:

❌ Not recommended
if x > 5 and x % 2 == 0:
    print("x is larger than 5 and divisible by 2!")

В приведенном выше примере оператор and имеет наименьший приоритет. Поэтому, возможно, будет более понятным выразить оператор if следующим образом:

✅ Recommended
if x>5 and x%2==0:
    print("x is larger than 5 and divisible by 2!")

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

Недопустимо следующее:

❌ Not recommended
if x >5 and x% 2== 0:
    print("x is larger than 5 and divisible by 2!")

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

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

✅ Recommended
a_list[3:4]

# Treat the colon as the operator with lowest priority.
a_list[x+1 : x+2]

# In an extended slice, you must surround both colons
# with the same amount of whitespace.
a_list[3:4:5]
a_list[x+1 : x+2 : x+3]

# You omit the space if you omit a slice parameter.
a_list[x+1 : x+2 :]

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

Когда следует избегать добавления пробелов

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

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

trailing_whitespace.py
x = 1 + 2 + \ 
    3 + 4

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

Этот завершающий пробел не позволяет Python воспринимать его как маркер продолжения строки и приведет к синтаксической ошибке:

$ python trailing_whitespace.py
  File "trailing_whitespace.py", line 1
    x = 1 + 2 + \ 
                 ^
SyntaxError: unexpected character after line continuation character


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

В PEP 8 также описаны некоторые другие случаи, когда вам следует избегать пробелов:

  • Непосредственно внутри круглых скобок:

    # ✅ Recommended
    numbers = [1, 2, 3]
    
    # ❌ Not recommended
    numbers = [ 1, 2, 3, ]
    
  • Перед запятой, точкой с запятой или двоеточием:

    x = 5
    y = 6
    
    # ✅ Recommended
    print(x, y)
    
    # ❌ Not recommended
    print(x , y)
    
  • Перед открывающей круглой скобкой, с которой начинается список аргументов вызова функции:

    def double(x):
        return x * 2
    
    # ✅ Recommended
    double(3)
    
    # ❌ Not recommended
    double (3)
    
  • Перед открытой скобкой, с которой начинается индекс или фрагмент:

    # ✅ Recommended
    a_list[3]
    
    # ❌ Not recommended
    a_list [3]
    
    
    
  • Между конечной запятой и закрывающей круглой скобкой:

    # ✅ Recommended
    a_tuple = (1,)
    
    # ❌ Not recommended
    a_tuple = (1, )
    
  • Для выравнивания операторов присваивания:

    # ✅ Recommended
    var1 = 5
    var2 = 6
    some_long_var = 7
    
    # ❌ Not recommended
    var1          = 5
    var2          = 6
    some_long_var = 7
    

Самое важное - убедиться, что в вашем коде нигде нет завершающих пробелов. Кроме того, в других случаях PEP 8 не рекомендует добавлять дополнительные пробелы, например, непосредственно внутри квадратных скобок, а также перед запятыми и двоеточиями. Также не следует добавлять дополнительные пробелы для выравнивания операторов.

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

“Простое лучше сложного”.

— Дзен Python

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

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

❌ Not recommended
is_bigger = 6 > 5
if is_bigger == True:
    return "6 is bigger than 5"

В использовании оператора эквивалентности (==) здесь нет необходимости. bool может принимать только значения True или False. Для этого достаточно написать следующее:

✅ Recommended
is_bigger = 6 > 5
if is_bigger:
    return "6 is bigger than 5"

Этот способ выполнения инструкции if с логическим значением требует меньше кода и является более простым, поэтому PEP 8 рекомендует его.

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

❌ Not recommended
a_list = []
if not len(a_list):
    print("List is empty!")

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

✅ Recommended
a_list = []
if not a_list:
    print("List is empty!")

В то время как в обоих примерах будет напечатан List is empty!, второй вариант более прост для чтения и понимания, поэтому он рекомендуется в PEP 8.

Используйте is not вместо not ... is в операторах if. Если вы пытаетесь проверить, имеет ли переменная определенное значение, есть два варианта. Первый - вычислить оператор if с помощью x is not None, как в примере ниже:

✅ Recommended
if x is not None:
    return "x exists!"

Вторым вариантом было бы вычислить x is None, а затем получить if утверждение, основанное на not результате:

❌ Not recommended
if not x is None:
    return "x exists!"

Хотя Python правильно оценит оба варианта, первый более прост, поэтому PEP 8 рекомендует его.

Не используйте if x:, когда вы имеете в виду if x is not None:. Иногда у вас может быть функция с аргументами, равными None по умолчанию. Распространенной ошибкой при проверке того, имеет ли такой аргумент, arg, другое значение, является использование следующего:

❌ Not recommended
if arg:
    print(arg)

Этот код проверяет, соответствует ли arg. Вместо этого вы хотите проверить, соответствует ли arg not None, поэтому лучше использовать следующее:

✅ Recommended
if arg is not None:
    print(arg)

Ошибка здесь заключается в предположении, что not None и truthy эквивалентны, но это не так. Вы могли бы задать для arg пустой список ([]). Как вы видели выше, пустые списки в Python также оцениваются как ложные. Таким образом, даже если вы присвоили значение arg, условие не выполняется, и Python не будет выполнять код в теле инструкции if:

>>> arg = []

>>> if arg:
...     print(arg)
...

>>> if arg is not None:
...     print(arg)
...
[]


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

Используйте .startswith() и .endswith() вместо нарезки. Если вы пытались проверить, имеет ли строка word префикс или суффикс слова cat, то может показаться разумным использовать нарезка списка. Однако при разбиении списков часто возникают ошибки, и вам приходится жестко кодировать количество символов в префиксе или суффиксе. Человеку, менее знакомому с разбиением списков на Python, также непонятно, чего вы пытаетесь достичь:

❌ Not recommended
if word[:3] == "cat":
    print("The word starts with 'cat'")

Однако это не так легко читается, как при использовании .startswith():

✅ Recommended
if word.startswith("cat"):
    print("The word starts with 'cat'")

Аналогично, тот же принцип применяется при проверке суффиксов. В приведенном ниже примере показано, как можно проверить, заканчивается ли строка на "jpg":

❌ Not recommended
if file_name[-4:] == ".jpg":
    print("The file is a JPEG")

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

✅ Recommended
if file_name.endswith(".jpg"):
    print("The file is a JPEG")

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

Когда следует игнорировать PEP 8

Краткий ответ на этот вопрос - никогда. Если вы будете точно следовать п. 8, вы можете гарантировать, что у вас будет чистый, профессиональный и читаемый код. Это принесет пользу как вам, так и сотрудникам и потенциальным работодателям.

Однако некоторые рекомендации, содержащиеся в ОПТОСОЗ 8, неудобны в следующих случаях:

  • Если соблюдение PEP 8 нарушит совместимость с существующим программным обеспечением
  • Если код, над которым вы работаете, не соответствует PEP 8
  • Если код должен оставаться совместимым со старыми версиями Python

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

Советы и рекомендации, которые помогут убедиться, что ваш код соответствует требованиям PEP 8

Нужно многое запомнить, чтобы убедиться, что ваш код соответствует руководству по стилю для кода на Python. Запомнить все эти правила при разработке кода может оказаться непростой задачей. Особенно много времени отнимает обновление предыдущих проектов до соответствия PEP 8. К счастью, существуют инструменты, которые могут помочь ускорить этот процесс. Существует два класса инструментов, которые могут помочь вам применить эти правила стиля: средства компоновки и автоформатировщики.

Линтеры

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

Некоторые хорошие средства компоновки для кода на Python - это pycodestyle, flake8, и ruff. Вы можете попробовать их с помощью следующего фрагмента кода, который содержит форматирование, не соответствующее PEP 8:

unfashionable.py
import math

numbers = [1,2,\ 
3,4]

def add_all_numbers_from_collection(
    number_one, number_two, number_three,
    number_four):
    return number_one+number_two + number_three +number_four

print (add_all_numbers_from_collection( *numbers ))

pycodestyle это инструмент для проверки вашего кода на Python на соответствие некоторым стилевым соглашениям в PEP 8.

Вы можете установить pycodestyle с помощью pip:

$ python -m pip install pycodestyle


Затем вы можете запустить pycodestyle со своего терминала, передав ему файл Python, который вы хотите проверить, в качестве аргумента:

$ pycodestyle unfashionable.py
unfashionable.py:3:13: E231 missing whitespace after ','
unfashionable.py:3:15: E231 missing whitespace after ','
unfashionable.py:3:16: E502 the backslash is redundant between brackets
unfashionable.py:4:1: E128 continuation line under-indented for visual indent
unfashionable.py:4:2: E231 missing whitespace after ','
unfashionable.py:6:1: E302 expected 2 blank lines, found 1
unfashionable.py:8:5: E125 continuation line with same indent as next logical line
unfashionable.py:9:50: E225 missing whitespace around operator
unfashionable.py:11:1: E305 expected 2 blank lines after class or function definition, found 1
unfashionable.py:11:6: E211 whitespace before '('
unfashionable.py:11:40: E201 whitespace after '('
unfashionable.py:11:49: E202 whitespace before ')'
unfashionable.py:11:52: W292 no newline at end of file


Программа компоновки выводит номера строк и столбцов, в которых было обнаружено нарушение стиля. Она также выдает код ошибки для конкретного нарушения стиля вместе с кратким описанием проблемы.

Еще одним популярным вариантом для редактирования вашего кода на Python является flake8. Это инструмент, который объединяет другие проекты, такие как обнаружение ошибок с помощью pyflakes, с pycodestyle.

Опять же, вы можете установить flake8 с помощью pip:

$ python -m pip install flake8


Затем вы можете запустить flake8 из терминала и передать ему файл, который вы хотите проверить, в качестве аргумента:

$ flake8 unfashionable.py
unfashionable.py:1:18: E999 SyntaxError: unexpected character after line continuation character


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

После того, как вы исправите синтаксическую ошибку, удалив завершающий пробел в строке 3, повторный запуск flake8 покажет почти те же нарушения стиля, которые вы видели раньше:

$ flake8 unfashionable.py
unfashionable.py:1:1: F401 'math' imported but unused
unfashionable.py:3:13: E231 missing whitespace after ','
unfashionable.py:3:15: E231 missing whitespace after ','
unfashionable.py:3:16: E502 the backslash is redundant between brackets
unfashionable.py:4:1: E128 continuation line under-indented for visual indent
unfashionable.py:4:2: E231 missing whitespace after ','
unfashionable.py:6:1: E302 expected 2 blank lines, found 1
unfashionable.py:8:5: E125 continuation line with same indent as next logical line
unfashionable.py:9:50: E225 missing whitespace around operator
unfashionable.py:11:1: E305 expected 2 blank lines after class or function definition, found 1
unfashionable.py:11:6: E211 whitespace before '('
unfashionable.py:11:40: E201 whitespace after '('
unfashionable.py:11:49: E202 whitespace before ')'
unfashionable.py:11:52: W292 no newline at end of file


В дополнение к нарушениям стиля PEP 8, помеченным как E ошибки, вы также получили ошибку типа F. Эта ошибка указывает на то, что в вашем скрипте есть неиспользуемый импорт модуля math.

В то время как pycodestyle устраняет нарушения стиля PEP 8, flake8 сочетает в себе множество инструментов и, следовательно, может также помочь вам выявить синтаксические и логические ошибки, такие как неиспользуемый импорт, и даже проблемы сложности. Скоро вы познакомитесь с ruff.

Примечание: Еще одним популярным компоновщиком для вашего кода на Python является Pylint.

Многие средства компоновки также доступны в виде расширений для Sublime Text, Visual Studio Code и даже VIM. Если вы еще не нашли свою любимую IDE или текстовый редактор, то можете начать с изучения VS Code или Sublime Text.

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

Автоформатеры

Автоформатировщики - это программы, которые автоматически преобразуют ваш код в соответствии с PEP 8. Как только такая программа будет black,, которая автоматически форматирует код, соответствующий большинству правил в PEP 8. Одно большое отличие заключается в том, что длина строки ограничена 88 символами, а не 79. Однако вы можете изменить это, добавив флажок командной строки, как вы увидите в примере ниже.

Примечание: Два других автоформатера, autopep8 и yapf, выполняют действия, аналогичные тем, что выполняет black. Ruff также поддерживает автоформатирование.

Вы можете установить black с помощью pip:

$ python -m pip install black


Вы можете запустить black через командную строку, так же, как вы делали это с компоновщиками ранее. Взгляните еще раз на код в unfashionable.py, который вы хотите исправить:

unfashionable.py
import math

numbers = [1,2,\
3,4]

def add_all_numbers_from_collection(
    number_one, number_two, number_three,
    number_four):
    return number_one+number_two + number_three +number_four

print (add_all_numbers_from_collection( *numbers ))

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

Затем вы можете запустить следующую команду из командной строки:

$ black unfashionable.py
reformatted unfashionable.py

All done! ✨ 🍰 ✨
1 file reformatted.


После того, как black автоматически переформатирует unfashionable.py, это будет выглядеть следующим образом:

unfashionable.py
import math

numbers = [1, 2, 3, 4]


def add_all_numbers_from_collection(number_one, number_two, number_three, number_four):
    return number_one + number_two + number_three + number_four


print(add_all_numbers_from_collection(*numbers))

Это выглядит значительно лучше, чем раньше, но все аргументы для add_all_numbers_from_collection() увеличивают масштаб определения функции до 79 символов, рекомендованных в PEP 8. Как вы уже знали, в black вместо этого используется ограничение в 88 символов.

Если вы хотите изменить ограничение длины строки, то вы можете использовать флаг --line-length:

$ black --line-length=79 unfashionable.py
reformatted unfashionable.py

All done! ✨ 🍰 ✨
1 file reformatted.


После того, как вы ограничили длину строки при втором запуске, ваш автоформатированный код теперь выглядит великолепно и полностью соответствует руководству по стилю для кода на Python:

unfashionable.py
import math

numbers = [1, 2, 3, 4]


def add_all_numbers_from_collection(
    number_one, number_two, number_three, number_four
):
    return number_one + number_two + number_three + number_four


print(add_all_numbers_from_collection(*numbers))

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

$ flake8 unfashionable.py
unfashionable.py:1:1: F401 'math' imported but unused


Разве не было бы неплохо, если бы существовал инструмент, который объединял бы верстку и форматирование под одной крышей?

Комбинированный инструмент

Ruff - популярный инструмент в сообществе Python, который может выступать как в качестве линтера, так и в качестве автоформаттера. Это инструмент командной строки, написанный на Rust и, следовательно, способный выполнять очень быстро.

Вы можете установить Ruff с помощью pip:

$ python -m pip install ruff


Теперь вы можете использовать Ruff как для верстки, так и для форматирования вашего кода:

$ ruff check unfashionable.py
unfashionable.py:1:8: F401 [*] `math` imported but unused
Found 1 error.
[*] 1 fixable with the `--fix` option.


Ruff немедленно находит неиспользуемый импорт и даже дает вам возможность исправить его. Следуйте предложению из выходных данных и исправьте этот неиспользуемый math импорт автоматически:

$ ruff check --fix unfashionable.py
Found 1 error (1 fixed, 0 remaining).


Ваша неиспользованная инструкция по импорту - это история. Если вы запустите проверку исходного неформатированного файла unfashionable.py, то заметите, что Ruff не помечает нарушения стиля, которые были отмечены в pycodestyle или flake8. В настройках по умолчанию Ruff не помечает большинство ошибок ввода E, но вы можете изменить это в файле настроек .

А поскольку Ruff является одновременно и линтером, и автоформатером, вам даже не нужно беспокоиться об этом. Если вы запустите команду инструмента format, то она исправит все нарушения стиля PEP 8, причем вам даже не нужно будет знать, что они были изначально:

$ ruff format unfashionable.py
1 file reformatted


При настройках по умолчанию автоформатер Ruff выдаст следующий отформатированный код:

unfashionable.py
numbers = [1, 2, 3, 4]


def add_all_numbers_from_collection(number_one, number_two, number_three, number_four):
    return number_one + number_two + number_three + number_four


print(add_all_numbers_from_collection(*numbers))

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

Если вы хотите узнать больше о работе с линтерами и автоформатерами, то можете ознакомиться с "Качество кода на Python: инструменты и рекомендации", в котором подробно объясняется, как использовать используйте некоторые из этих инструментов.

Заключение

Теперь вы знаете, как писать высококачественный, читаемый код на Python, используя рекомендации, изложенные в PEP 8. Хотя эти рекомендации могут показаться педантичными, следование им действительно может улучшить ваш код, особенно когда речь идет о том, чтобы поделиться своим кодом с потенциальными работодателями или сотрудниками.

В этом уроке вы узнали:

  • Что такое PEP 8 и почему он существует
  • Почему вы должны стремиться написать Код, совместимый с PEP 8
  • Как написать код, который соответствует руководству по стилю для кода на Python
  • Как использовать средства компоновки и автоформатирования для проверки вашего кода на соответствие рекомендациям PEP 8 и автоматического применения некоторых из них

Если вы хотите узнать больше о PEP 8, вы можете ознакомиться с полной документацией или посетить страницу pep8.org , в которой содержится то же самое информация, но была отформатирована для лучшей читабельности. В этих документах вы найдете остальные рекомендации PEP 8, с которыми вы не сталкивались в этом руководстве.

Есть ли у вас какие-либо проблемы, которые отличаются от того, что предлагается в PEP 8, или вы полностью согласны с руководством по стилю кода на Python? Поделитесь своим мнением в комментариях ниже.

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

<отметить класс="marker-highlight"> Пройдите тест: Проверьте свои знания с помощью нашего интерактивного теста “Как писать красивый код на Python с помощью PEP 8”. По завершении вы получите оценку, которая поможет вам отслеживать прогресс в обучении:

<время работы/> How to Write Beautiful Python Code With PEP 8

Интерактивная викторина

Как написать красивый код на Python с помощью PEP 8

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

Часто задаваемые вопросы

Теперь, когда вы ознакомились с PEP 8, вы можете использовать вопросы и ответы, приведенные ниже, чтобы проверить свое понимание и резюмировать то, что вы узнали.

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

PEP 8 - это документ, который содержит рекомендации и рекомендации по написанию кода на Python для улучшения его читаемости и согласованности.

Да, рекомендуется следовать PEP 8, поскольку это улучшает читаемость и согласованность кода, упрощая его понимание и совместную работу с другими пользователями над проектами на Python.

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

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

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

Вы можете использовать средства компоновки, такие как pycodestyle или flake8, для выявления нарушений стиля, а также автоформатировщики, такие как black или ruff, для автоматического форматирования вашего кода в соответствии с PEP 8.

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

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

В PEP 8 предлагается использовать строчные буквы с подчеркиванием для функций и переменных (snake case), camel case для классов и прописные буквы с подчеркиванием для констант. Выбирайте описательные названия, чтобы улучшить читаемость кода.

<статус завершения article-slug="python-pep8" class="btn-group mb-0" data-api-article-bookmark-url="/api/v1/articles/python-pep8/bookmark/" url статуса завершения data-api-article-url="/api/v1/articles/python-pep8/завершение_статуса/"> <кнопка поделиться bluesky-text="Интересная статья на #Python от @realpython.com :" email-body="Ознакомьтесь с этой статьей о Python:%0A%0Ah Как написать красивый код на Python с помощью PEP 8" email-subject="Статья на Python для вас" twitter-text="Интересная статья на #Python статья от @realpython:" url="https://realpython.com/python-pep8 /" url-title="Как написать красивый код на Python с помощью PEP 8">

Смотрите сейчас, к этому уроку прилагается соответствующий видеокурс, созданный командой Real Python. Посмотрите его вместе с письменным руководством, чтобы углубить свое понимание: Написание красивого кода на Python с помощью PEP 8

Back to Top