Как написать красивый код на Python с помощью PEP 8
Оглавление
- Почему нам нужен БОДРЯЩИЙ настрой 8
- Соглашения об именовании
- Расположение кода
- Отступы
- Комментарии
- Пробелы в выражениях и инструкциях
- Рекомендации по программированию
- Когда следует игнорировать PEP 8
- Советы и рекомендации, которые помогут убедиться, что ваш код соответствует требованиям 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”. По завершении вы получите оценку, которая поможет вам отслеживать прогресс в обучении:
<время работы/>
Интерактивная викторина
Как написать красивый код на 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 символов, полезно использовать отступы для улучшения читаемости. Это позволяет читателю различать две строки кода и одну строку кода, занимающую две строки. Вы можете использовать два стиля отступов:
- Выравнивание по начальному разделителю
- Отступ для зависания
Первый из этих двух способов заключается в том, чтобы выровнять блок с отступом по начальному разделителю:
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 символов вынуждает вас добавлять в код переносы строк. Для улучшения читабельности, вы должны сделать отступ в виде непрерывной строки, чтобы показать, что это непрерывная строка.
Как показано выше, есть два способа сделать это:
- Выровняйте блок с отступом по начальному разделителю.
- Используйте отступ с отступом в виде висячего элемента.
Вы можете выбрать любой из этих двух подходов для создания отступов в вашем коде после разрыва строки.
Куда ставить закрывающую скобку
Продолжения строк позволяют заключать строки в круглые или фигурные скобки. Возможно, закрывающая скобка не является основным элементом вашего внимания при программировании, но все же важно поместить ее в удобное для вас место. В противном случае это может сбить читателя с толку.
В 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, следующие двоичные операторы заключите в одинарный пробел с обеих сторон:
Операторы присваивания:
=,+=,-=, и так далееСравнения:
==,!=,>,<.>=,<=,is,is not,in, иnot inКогда вы используете знак равенства (
=) для присвоения значения по умолчанию аргументу, не заключайте его в пробелы:# ✅ 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. Вместо этого вы хотите проверить, соответствует лиargnot 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”. По завершении вы получите оценку, которая поможет вам отслеживать прогресс в обучении:
<время работы/>![]()
Интерактивная викторина
Как написать красивый код на 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