Обзор руководства по стилю PEP 8

Создайте стиль со своим кодом Python.

Python Enhancement Proposal 8 или PEP 8 - это подробное руководство по стилю вашего кода Python. Цель PEP 8 - объединить весь Python в одном руководстве по стилю. Это увеличивает читаемость и общее понимание кода Python. PEP 8 не всегда подразумевает соблюдение при любых обстоятельствах. Вы столкнетесь с кодом, который просто неприменим, и если да, то вам, возможно, придется ненадолго оторваться от руководства по стилю. Ключевым моментом является использование руководства по стилю при любой возможности. Это поможет вам и всем, кто видит ваш код, читать его и работать над ним. Я расскажу о тех областях, которые считаю наиболее важными. Я не буду перебирать некоторые области и другие, я могу просто бегло просмотреть. Я действительно рекомендую прочитать PEP 8 полностью, так как это руководство предназначено скорее как краткий обзор. Чтобы действительно понять и получить более подробные объяснения, а также части, которые я решил не включать в эту статью. Я рассмотрю следующие разделы PEP 8:

  • Макет кода
  • Струны
  • Пробел
  • Завершающие запятые
  • Комментарии
  • Соглашения об именах
  • Рекомендации

PEP 8 можно найти здесь:



PEP 8 - Руководство по стилю кода Python
Официальный сайт языка программирования Python www.python.org



Макет кода

Отступ:

  • 4 пробела, хотя это зависит от вас в строках продолжения, если есть какой-либо отступ.
  • Вы можете выстроить завернутые элементы в круглые скобки по вертикали или с выступом.
# 4 space indent
def hello(var):
    print(var)
# vertical alignment
example2 = function(first_var, second_var,
                    third_Var, fourth_var)
# hanging indent
example3 = function(
    first_var, second_var,
    third_var, fourth_var)
  1. Вы можете использовать аналогичные рабочие процессы для условных выражений, которые либо слишком длинные, либо вы хотите быть продолжением строки. Вы можете использовать круглые скобки после двухсимвольного ключевого слова, чтобы сделать отступ автоматически при переходе к новой строке. Это может быть полезно для длинных условных операторов, таких как оператор if. Для вложенных операторов вы можете выбрать отсутствие дополнительного отступа, прокомментировать детали отступа или добавить дополнительный отступ.
  2. Вы можете поставить рядом закрывающую пунктуацию (фигурную скобку, скобку или круглую скобку) первым символом последней строки или первым символом, с которого начинается многострочное выражение, не являющееся пробелом.
# last line, first character
new_list = [
    'one', 'two', 'three',
    'four', 'five', 'six'
    ]
# first line, first character
new_list = [
    'one', 'two', 'three',
    'four', 'five', 'six'
]

Вкладки и пробелы

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

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

  1. Максимальная длина строки должна составлять 79 символов, хотя я иногда нахожу это ограничивающим и в таких случаях должен быть длиннее. В подобных ситуациях можно использовать до 99 символов.
  2. Для комментариев и строк документации следует использовать 72 символа, и их нельзя увеличивать.
  3. Это помогает при чтении кода Python и хранении его в инструментах редактора, проверки и отладки.
  4. Чтобы помочь вам не сбиться с пути, у Python есть помощник для этого. Вы можете заключить свои строки в круглые скобки, начиная со всего, что стоит за первым ключевым словом, и заканчивая перед следующим ключевым словом. Это рекомендуется в PEP 8 и автоматически переносит ваши строки в соответствии с правильным форматом стиля строк Python.
  5. Обратную косую черту также можно использовать, только если не применяется перенос скобок, например, в операторах assert.

Разрывы строк с бинарными операторами

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

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

  1. Две пустые строки должны быть как до, так и после определения класса.
  2. Одна пустая строка должна быть как до, так и после определения метода.
  3. Вы должны консервативно использовать пустые строки в своем коде для разделения групп функций.
  4. Вам не нужно включать пустые строки между разными строками, если каждая из этих строк представляет собой всего лишь строку кода, отдельную друг от друга.
  5. Python использует символ подачи формы control-L (^ L) для пробела.

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

  1. Код должен использовать UTF-8 для основного дистрибутива Python 3 (ASCII для Python 2) и не должен иметь объявлений.
  2. Кодировки за пределами этого следует использовать только в тестовых целях.
  3. Перейдите к PEP 3131 для получения дополнительной информации об этой политике.
  4. Идентификаторы должны быть только в формате ASCII, и по возможности следует использовать английские слова.

Импорт

  1. Импорт обычно не имеет пустых строк, разделяющих их.
  2. Импорты обычно следует разделять на разные строки, если не используется ключевое слово from.
  3. Импорт находится в верхней части вашего кода после комментариев и строк документации и перед глобальными переменными и константами.
  4. Импорт должен быть в таком порядке.
  • Стандартная библиотека
  • Третья сторона
  • Местный / специфический для библиотеки.

5. Рекомендуется абсолютный импорт, но явный относительный импорт вполне подойдет. Какой из вариантов менее подробный.

6. Импортируйте классы из отдельных модулей классов.

7. Импорт подстановочных знаков (*) не следует использовать без необходимости.

8. «dunders» уровня модуля - это имена с двумя завершающими знаками подчеркивания. Эти имена следует размещать после комментариев и строк документации, но перед импортом.

9. Импорт from __future__ должен быть перед любым кодом, кроме комментариев и строк документации.

Струны

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

Пробел

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

  1. Не используйте лишние пробелы в своих выражениях и утверждениях. У вас должны быть пробелы после запятых, двоеточий и точек с запятой, если они не заканчиваются после скобок, фигурных скобок или круглых скобок.
  2. С любыми операторами вы должны использовать пробелы по обе стороны от оператора. Двоеточие для нарезки считается бинарным оператором, и между ними не должно быть пробелов.
  3. У вас должны быть круглые скобки без пробелов, непосредственно рядом с функцией при вызове функций function().
  4. при индексировании или нарезке скобки должны находиться непосредственно рядом с коллекцией без пробелов collection[‘index’].
  5. Не рекомендуется использовать пробелы для выравнивания значений переменных.
  6. Убедитесь, что вы согласны с форматами, которые вы выбираете, когда доступны дополнительные варианты.

Завершающие запятые

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

Комментарии

  1. Убедитесь, что ваши комментарии имеют смысл и полезны для чтения кода. Комментарии, которые являются контрпродуктивными, могут ухудшить читаемость кода.
  2. Не забудьте обновить свои комментарии при обновлении кода.
  3. Убедитесь, что ваши комментарии понятны другим программистам Python.
  4. Блочные комментарии - это абзац или несколько однострочных комментариев, оканчивающихся конечной пунктуацией для каждой строки. Они должны начинаться с #, а затем с пробела. Кроме того, комментарии блока должны иметь такой же отступ, как и код, в который они собираются. Разделите абзацы одной строкой комментария, в которой ничего не должно быть.
  5. В многострочных комментариях используйте два пробела после периода предложения, кроме одного пробела после последнего предложения.
  6. Встроенные комментарии - это комментарии, которые следуют за вашим кодом в одной строке. Встроенные комментарии следует использовать консервативно. Они должны быть разделены как минимум двумя пробелами после вашего кода. Их следует использовать только при необходимости.
  7. Строки документации или строки документации делают именно то, что они заявляют. Они предоставляют документацию по модулям, функциям, классам и методам. У вас должны быть документы для всего следующего. Строки документов создаются с использованием тройных “”” кавычек в начале и в конце строки документации. Чтобы узнать больше о строках документации, посмотрите PEP 257.

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

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

Принцип приоритетности - это то, в чем вы должны отражать использование, а не реализацию ваших общедоступных аспектов ваших API.

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

b  
B  
lowercase  
lower_case_underscore
UPPERCASE
UPPER_CASE_UNDERSCORE
CamelCase
mixedCase
Cap_words_Underscore # not recommended

4. Обязательные правила присвоения имен

  • Одиночный знак подчеркивания в начале: слабый и не рекомендуется, кроме случаев внутреннего использования.
  • Одинарное подчеркивание в конце: используется, чтобы избежать проблем с ключевыми словами Python.
  • Двойное подчеркивание в начале: для именования атрибутов класса.
  • Двойное подчеркивание в начале и в конце - это «магические объекты или атрибуты в пространстве имен пользователя.

Имена, которых следует избегать:

# try not to use.
l  # lowercase L
O  # uppercase o
I  # uppercase i

Совместимость ASCII:

  • Идентификаторы должны быть совместимы с ASCII для стандартной библиотеки.

Имена пакетов и модулей:

  • Пакеты и модули должны иметь, по возможности, короткие и строчные имена.
  • Модули могут иметь подчеркивание.
  • Пакеты не должны иметь подчеркивания.
  • Если модуль написан на C или C ++ и связан с модулем Python, он создает интерфейс более высокого уровня и может быть назван с начальным подчеркиванием.

Имена классов:

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

Имена переменных типа:

  • Переменные типа должны использовать условные обозначения заглавных слов и короткие имена.
  • Суффикс _co для переменных с ковариантным поведением.
  • Суффикс _contra для переменных с контравариантным поведением.

Имена исключений:

  • Используйте соглашения об именах классов.
  • Суффикс Error используется для имен исключений, которые вызывают эту ошибку.

Имена глобальных переменных:

  • Следуйте соглашениям об именах функций.
  • Механизм __all__ следует использовать для предотвращения глобальных переменных, вызванных from M import *, или использовать его аналогично префиксу globals.

Имена функций и переменных:

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

Аргументы функции и метода:

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

Имена методов и переменные экземпляра:

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

Константы:

  • ВЕРХНИЙ РЕГИСТР Соглашение об именах с подчеркиванием.

Наследование:

  • Убедитесь, что атрибуты вашего класса являются общедоступными или закрытыми.
  • Непубличные атрибуты - это атрибуты, не предназначенные для третьих лиц.
  • «Частный» - это термин, используемый в Python.
  • «Подкласс API» (также известный как «защищенный»). Создан для наследования от. Базовые классы.
  • Общедоступные атрибуты = без начальных подчеркиваний, если не возникают конфликты ключевых слов.
  • Предоставлять только имена атрибутов для атрибутов общедоступных данных.
  • подклассы могут быть названы с двойным подчеркиванием в начале, чтобы использовать диспетчер имен Python.

5. Общедоступные и внутренние интерфейсы

  • Пользователи должны уметь различать общедоступные и внутренние интерфейсы.
  • Если интерфейс задокументирован, он считается общедоступным, если иное не указано в документации.
  • Недокументированные интерфейсы являются внутренними.
  • Модули должны использовать __all__ для объявления общедоступного API. если __all__ установлен в пустой список, это говорит о том, что общедоступного API нет.
  • Одиночный символ подчеркивания для внутренних интерфейсов.
  • Если какое-либо пространство имен является внутренним, то интерфейс является внутренним.
  • Импорт - это деталь реализации.

Рекомендации

  1. Напишите код, чтобы он не повлиял отрицательно на другие реализации Python.
  2. is или is not для сравнения синглтонов.
  3. is not, а не not is.
  4. Используйте def вместо присваивания при привязке лямбда-выражений к идентификаторам.
  5. Для исключений используйте Exception вместо BaseException.
  6. Убедитесь, что ваша цепочка исключений используется правильно.
  7. По возможности будьте конкретны с исключениями.
  8. Используйте явный синтаксис привязки имени.
  9. Используйте явную иерархию исключений для ошибок операционной системы.
  10. При использовании try и except держите код как можно плотнее вокруг области, которая должна быть заключена в блок try.
  11. Используйте инструкции with на локальных ресурсах.
  12. Убедитесь, что вы правильно используете операторы return. Либо есть return выражения, либо нет.
  13. Строковые методы в отличие от строкового модуля.
  14. Используйте методы .startswith() и .endswith() для нарезки строковых префиксов и суффиксов.
  15. Используйте isinstance(<item>, <item>) вместо if type(<item>) is type(<item>).
  16. Пустые последовательности считаются False.
  17. Не используйте == для True False сравнений.
  18. Операторы управления потоком должны находиться внутри finally блоков кода.

Аннотации функций

  • См. Описание функций в PEP 484.

Аннотации переменных

  • См. PEP 526 для аннотаций переменных.

Вывод

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



PEP 8 - Руководство по стилю кода Python
Официальный сайт языка программирования Python www.python.org





python / peps
Название: Руководство по стилю для кода Python Версия: $ Revision $ Последнее изменение: $ Date $ Автор: Гвидо ван Россум, Барри Варшава… github.com