Учебное пособие по Python PEP 8: начните писать читаемый код

Предложение по улучшению Python 8 или PEP 8 — это руководство по стилю кода Python. В 2001 году Гвидо ван Россум, Барри Варшава и Ник Коглан создали PEP 8, чтобы помочь программистам Python писать согласованный и читаемый код. Руководство по стилю не всегда применимо к вашей работе, но это важный и полезный инструмент, который улучшит ваш процесс написания кода. Сегодня мы представим краткий обзор некоторых основных частей руководства по стилю PEP 8 Python, включая соглашения об именах, макет кода, комментарии и многое другое.

Зачем использовать PEP 8?

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

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

Соглашения об именах PEP 8

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

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

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

В таблице ниже мы описываем некоторые соглашения об именах в Python:

Тип	соглашение	Примеры
Имена классов	Используйте верблюжий футляр. Каждое слово начинайте с заглавной буквы. Не используйте символы подчеркивания для разделения слов.	Наш класс Учебный класс
Постоянные имена	Используйте одну заглавную букву, слово или слова. Используйте подчеркивание для разделения слов.	OUR_CONSTANT ПОСТОЯННЫЙ
Имена функций	Используйте слово или слова в нижнем регистре. Используйте подчеркивание для разделения слов.	наша_функция функция
Имена методов	Используйте слово или слова в нижнем регистре. Используйте подчеркивание для разделения слов.	наш_метод метод
Имена модулей	Используйте короткие слова или слова в нижнем регистре. Используйте подчеркивание для разделения слов.	our_module.py module.py
Имена пакетов	Используйте короткие слова или слова в нижнем регистре. Не используйте символы подчеркивания для разделения слов.	нашпакет упаковка
Имена переменных	Используйте одну строчную букву, слово или слова. Используйте подчеркивание для разделения слов.	наша_переменная Икс

Выбор имен

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

Макет кода PEP 8

Пробел

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

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

Мы должны избегать использования пробелов в следующих ситуациях:

• Внутри скобок, скобок или фигурных скобок

# Do this:

fruit(banana[1], {strawberry: 2})

# Not this:

fruit( banana[ 1 ], { strawberry: 2 })

• Между запятыми и закрывающими скобками

# Do this:

foo = (1,)

# Not this:

foo = (1, )

• Прямо перед запятой, точкой с запятой или двоеточием

# Do this:

if x == 5: print x, y; x, y = y, x

# Not this:

if x == 5: print x , y ; x , y = y , x

• Прямо перед открывающей скобкой, с которой начинается список аргументов вызова функции

# Do this:

dog(1)

# Not this:

dog (1)

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

# Do this:

dct[«key»] = lst[index]

# Not this:

dct [«key»] = lst [index]

• Более одного пространства вокруг оператора, чтобы выровнять его с другим

1

2

# Do this:

x = 5

y = 10

our_variable = 20

# Not this:

x          = 5

y          = 10

our_variable = 20

• Избегайте конечных пробелов

Длина строки и разрывы строк

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

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

Если нам нужно использовать разрыв строки вокруг двоичных операторов, таких как +и *, мы должны поместить его перед оператором следующим образом:

# Do this:

total = (first_variable

         + second_variable

         — third_variable)

# Not this:

total = (first_variable +

         second_variable —

         third_variable)

Отступ

Отступы очень важны при написании кода Python. Уровни отступа определяют, как операторы группируются вместе. Основные правила отступов PEP 8 включают:

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

Давайте посмотрим на пример:

x = 20

if x > 50:

  print(«x is greater than 50»)

В приведенном выше примере наш printоператор с отступом сообщает Python, что он должен выполнить оператор только в том случае, если ifоператор вернется True.

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

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

В Python 2 нет того же правила, а это значит, что мы не заметим ошибок, если будем использовать сочетание табуляции и пробелов. Чтобы убедиться, что мы используем последовательный метод отступов в Python 2, мы можем добавить -tфлаг при запуске нашего кода из командной строки. Интерпретатор выдаст нам предупреждение, если обнаружит какие-либо несоответствия. Если мы используем -ttфлаг, интерпретатор выдаст нам ошибки, а это значит, что наш код не будет работать.

PEP 8 комментариев

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

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

Еще одна хорошая практика комментирования включает ограничение длины строки наших комментариев и строк документации 72 символами. Если наши комментарии превышают 72 символа, мы должны начать новую строку. Мы также должны обновлять наши комментарии, если наш код изменяется по какой-либо причине. Давайте посмотрим на некоторые из различных типов комментариев и на то, как они вписываются в PEP 8:

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

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

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

Давайте посмотрим на пример:

for i in range(0,10):

    # Loop over i ten times and print the value of i

    # followed by a string of your name

    print(i, «Erin»)

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

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

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

x = 1 # This is an example of an inline comment!

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

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

• Окружите строки документации тремя двойными кавычками «»»с каждой стороны, например:»»»Hi, I’m a docstring!»«»
• Напишите строки документации для всех общедоступных классов, функций, методов и модулей.
• При написании многострочной строки документации поместите двойные кавычки, завершающие эту строку документа, в отдельной строке.
• При написании однострочной документации сохраняйте двойные кавычки в одной строке.

Линтеры и автоформаттеры

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

Линтеры

ЛИНТЕР анализируют наши программы и отмечают все имеющиеся у нас ошибки. Они дают нам советы, как исправить наши ошибки. Мы можем установить линтеры как расширения к нашим текстовым редакторам, что означает, что они будут отмечать ошибки при написании кода. Доступно множество различных линтеров Python. Давайте посмотрим на два самых популярных линтера:

Flake8

Flake8 является инструментом, который комбинаты pyflakes, pycodestyleи отладчик. Мы можем вызвать Flake8 из командной строки или через Python. Мы можем использовать Flake8 для проверки всего исходного кода или сузить область проверки, указав конкретные пути и каталоги, которые мы хотим просмотреть.

pycodestyle

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

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

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

autopep8

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

установка pip :

pip install —upgrade autopep8

easy_install :

easy_install -ZU autopep8

Давайте посмотрим на пример реализации autopep8 на простом коде Python:

Перед autopep8 :

import sys, os;

print(                 «hello»       );

После autopep8 :

import sys

import os

print(«hello»)

Black

Черный помогает решить незначительные стилистические и структурные проблемы, чтобы мы могли сосредоточиться на более серьезных проблемах с кодированием. Мы можем установить его, запустив pip install black. Если вы хотите его использовать, убедитесь, что у вас установлен Python 3.60+, иначе он не запустится. После установки Black мы можем сразу использовать его как инструмент командной строки.

Подведение итогов и следующие шаги

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

• Висячие отступы
• Форматирование операторов if
• Лямбда
• И многое другое