Чистыйкод дляпродолжающи х

• Название: Чистыйкод дляпродолжающи х
• Дата: 13.05.2023
• Размер: 7.85 Mb.
• Имя файла: Python_Chisty_kod_dlya_prodolzhayuschikh_2022_El_Sveygart.pdf
• Тип: Документы; #1127485
• страница: 7 из 40

Black: бескомпромиссная система
форматирования кода
Black автоматически форматирует код в ваших файлах
.py
. Хотя вы должны по- нимать правила форматирования, рассмотренные в этой главе, Black выполняет всю работу по стилевому оформлению за вас. Если вы участвуете в совместном проекте, то можете моментально урегулировать многие споры относительно фор- матирования кода — просто поручите решение Black.
У нас нет возможности изменить многие правила, которым следует Black, поэтому
Black описывается как «бескомпромиссная система форматирования кода». Соб- ственно, его название (Black — черный) происходит от знаменитого высказывания
Генри Форда относительно цветов выпускаемых автомобилей: «Цвет автомобиля может быть любым, при условии что он черный».

80
Глава 3.Форматирование кода при помощи Black
Я описал конкретные стилевые правила, используемые Black; полное руководство по стилю для Black вы найдете по адресу https://black.readthedocs.io/en/stable/
the_black_code_style.html.
Установка Black
Установите Black при помощи программы pip
, входящей в комплект поставки
Python. В Windows для этого следует открыть окно командной строки и ввести команду:
C:\Users\Al\>python -m pip install --user black
В macOS и Linux откройте окно терминала и введите команду python3
вместо python
(это следует делать во всех фрагментах кода в этой книге, где используется команда python
):
Als-MacBook-Pro:

al$ python3 -m pip install --user black
Ключ
-m приказывает Python запустить модуль pip как приложение (некоторые модули Python имеют соответствующую настройку). Чтобы убедиться в том, что установка прошла успешно, выполните команду python
-m black
. На экране должно появиться сообщение «
No paths given.
Nothing to do
» вместо «
No module named black
».
Запуск Black из командной строки
Black можно запустить для любого файла Python из командной строки или окна терминала. Кроме того, IDE или редактор кода позволяет запустить Black в фоновом режиме. Инструкции о том, как обеспечить работу Black с Jupyter Notebook, Visual
Studio Code, PyCharm и другими редакторами, вы найдете на домашней странице
Black по адресу https://github.com/psf/black/.
Допустим, вы хотите отформатировать файл с именем yourScript.py автоматически.
В командной строке Windows выполните следующую команду (в macOS и Linux используйте команду python3
вместо python
):
C:\Users\Al>python -m black yourScript.py
После выполнения этой команды содержимое yourScript.py будет отформатировано в соответствии с руководством по стилю Black.
Переменная среды
PATH
может быть уже настроена для прямого запуска Black.
В этом случае для форматирования yourScript.py достаточно ввести следующую команду:
C:\Users\Al>black yourScript.py

Black: бескомпромиссная система форматирования кода
81
Чтобы выполнить Black для каждого файла
.py в папке, укажите в команде папку вместо отдельного файла. Следующий пример Windows форматирует все файлы в папке
C:\yourPythonFiles
, включая ее вложенные папки:
C:\Users\Al>python -m black C:\yourPythonFiles
Передача папки пригодится в том случае, если ваш проект содержит несколько файлов Python и вы не хотите вводить отдельную команду для каждого файла.
Хотя Black довольно строго относится к форматированию кода, в следующих трех подразделах описаны некоторые параметры, которые вы можете настроить. Что- бы просмотреть полный набор ключей Black, выполните команду python
-m black
--help
Регулировка длины строки Black
Стандартная строка кода Python состоит из 80 символов. История 80-символьных строк уходит корнями в 1920-е годы, когда компания IBM представила перфокар- ты на 80 столбцов и 12 строк; 80-символьный стандарт стал использоваться для принтеров, мониторов и окон командной строки, появившихся через несколько десятилетий.
Но в XXI веке экраны с высоким разрешением позволяют выводить текст длиной более 80 символов. С большей длиной строки вам не придется выполнять верти- кальную прокрутку, чтобы просмотреть файл. С другой стороны, короткие строки не перегружены, а вы можете сравнить два исходных файла, разместив их на экране рядом друг с другом, без горизонтальной прокрутки.
Black по умолчанию использует строку длиной 88 символов. Выбор объясняется не очень убедительно: это на 10% больше стандартной 80-символьной строки.
Лично я предпочитаю 120 символов. Чтобы приказать Black форматировать код с 120-символьной (например) строкой, используйте ключ командной строки
-l
120
(буква l в нижнем регистре, не цифра 1). В Windows команда выглядит примерно так:
C:\Users\Al>python -m black -l 120 yourScript.py
Какую бы длину строки вы ни выбрали для своего проекта, для всех файлов
.py в проекте должно использоваться одинаковое значение.
Отключение настройки двойных кавычек для Black
Black автоматически изменяет все строковые литералы в вашем коде так, чтобы вместо одинарных кавычек они заключались в двойные кавычки, если только строка

82
Глава 3.Форматирование кода при помощи Black не содержит внутренние символы двойных кавычек; в этом случае используются одинарные кавычки. Допустим, файл yourScript.py содержит следующий фрагмент:
a = 'Hello' b = "Hello" c = 'Al\'s cat, Zophie.'
d = 'Zophie said, "Meow"' e = "Zophie said, \"Meow\"" f = '''Hello'''
После применения Black файл yourScript.py будет отформатирован следующим образом:
a = "Hello"
❶
b = "Hello"
c = "Al's cat, Zophie." d = 'Zophie said, "Meow"'
❷
e = 'Zophie said, "Meow"' f = """Hello"""
❸
В результате применения Black с настройками двойных кавычек код Python будет похож на код, написанный на других языках программирования, где строковые литералы часто заключаются в двойные кавычки. Обратите внимание: строки переменных a
, b
и c
используют двойные кавычки. Строка переменной d
сохраняет исходные одинарные кавычки, чтобы избежать исчезновения двойных кавычек в строке
❷
. Обратите внимание: Black также использует двойные кавычки для многострочных текстов Python, заключенных в тройные кавычки
❸
Но если вы хотите, чтобы ваши строковые литералы остались в том виде, в котором они были написаны, а тип используемых кавычек не изменялся, передайте Black ключ командной строки
-S
(обратите внимание: буква S в верхнем регистре). На- пример, при применении Black к исходному файлу yourScript.py в Windows будет получен следующий результат:
C:\Users\Al>python –m black -S yourScript.py
All done!
1 file left unchanged.
Также можно использовать ключи длины строки
-l и
-S
в одной команде:
C:\Users\Al>python –m black –l 120 -S yourScript.py
Предварительный просмотр изменений, вносимых Black
Хотя Black не переименовывает переменные и не изменяет работу программы, возможно, вам не понравятся стилевые изменения, предложенные Black. Если вы хотите оставить исходное форматирование, то либо используйте механизм контроля

Black: бескомпромиссная система форматирования кода
83
версий для исходного кода, либо создавайте резервные копии самостоятельно.
Также можно просмотреть изменения, которые внесет Black, без фактического из- менения файлов; для этого следует запустить Black с ключом командной строки
--diff
. В Windows это выглядит так:
C:\Users\Al>python -m black --diff yourScript.py
Эта команда выводит различия в формате diff
, который часто используется си- стемами контроля версий, но удобочитаем для людей. Например, если yourScript.py содержит строку weights=[42.0,3.1415,2.718]
, при выполнении с ключом
--diff будет выведен следующий результат:
C:\Users\Al\>python -m black --diff yourScript.py
--- yourScript.py 2020-12-07 02:04:23.141417 +0000
+++ yourScript.py 2020-12-07 02:08:13.893578 +0000
@@ -1 +1,2 @@
-weights=[42.0,3.1415,2.718]
+weights = [42.0, 3.1415, 2.718]
Знак «минус» означает, что Black удалит строку weights=[42.0,3.1415,2.718]
и за- менит ее строкой, которая выводится с префиксом «плюс»: weights
=
[42.0,
3.1415,
2.718]
. Учтите, что после того, как вы запустите Black для изменения файлов с ис- ходным кодом, отменить внесенные изменения уже не удастся. Необходимо либо создать резервные копии вашего исходного кода, либо воспользоваться системой контроля версий (такой как Git) перед запуском Black.
Отключение Black для отдельных частей кода
Каким бы замечательным ни был инструмент Black, возможно, вы не захотите, чтобы он форматировал некоторые части вашего кода. Например, я предпочитаю самостоятельно расставлять отступы в разделах, где я выравниваю несколько вза- имосвязанных команд присваивания, как в следующем примере:
# Константы для разных интервалов времени:
SECONDS_PER_MINUTE = 60
SECONDS_PER_HOUR = 60 * SECONDS_PER_MINUTE
SECONDS_PER_DAY = 24 * SECONDS_PER_HOUR
SECONDS_PER_WEEK = 7 * SECONDS_PER_DAY
Black удалит дополнительные пробелы перед оператором присваивания
=
, отчего они, по моему мнению, будут хуже читаться:
# Константы для разных интервалов времени:
SECONDS_PER_MINUTE = 60
SECONDS_PER_HOUR = 60 * SECONDS_PER_MINUTE
SECONDS_PER_DAY = 24 * SECONDS_PER_HOUR
SECONDS_PER_WEEK = 7 * SECONDS_PER_DAY

84
Глава 3.Форматирование кода при помощи Black
Добавив комментарии
#
fmt:
off и
#
fmt:
on
, можно запретить Black форматирование строк в этом фрагменте, а затем продолжить его:
# Константы для разных промежутков времени:
# fmt: off
SECONDS_PER_MINUTE = 60
SECONDS_PER_HOUR = 60 * SECONDS_PER_MINUTE
SECONDS_PER_DAY = 24 * SECONDS_PER_HOUR
SECONDS_PER_WEEK = 7 * SECONDS_PER_DAY
# fmt: on
Теперь запуск Black для этого файла не приведет к изменению отступов (и лю- бого другого форматирования) в коде между этими двумя комментариями.
Итоги
Хотя хорошее форматирование люди часто не замечают, плохое форматирование вызывает раздражение. Стиль — понятие субъективное, но у разработчиков обычно вырабатываются общие представления о том, что считать хорошим или плохим форматированием; при этом, конечно же, остается место для личных предпочтений.
Синтаксис Python достаточно гибок в том, что касается стиля. Если вы пишете код, который никто никогда не увидит, вы можете писать его так, как вам нравится.
Но разработкой ПО чаще всего занимаются в команде. Работаете ли вы с другими программистами над проектом или просто хотите попросить более опытных коллег оценить вашу работу, важно отформатировать код в соответствии с общепринятыми руководствами по стилю.
Форматирование кода в редакторе — монотонная работа, которую можно автома- тизировать таким инструментом, как Black. В этой главе рассмотрены некоторые правила, которым следует Black, для того чтобы сделать ваш код более удобочитае- мым: вертикальные и горизонтальные отступы, чтобы код не был слишком плотным и хорошо читался, и ограничение длины каждой строки. Black следит за соблюдением этих правил за вас, что предотвращает возможные стилевые разногласия с коллегами.
Однако стиль программирования не сводится к применению отступов и выбору между одинарными и двойными кавычками. Например, использование содержа- тельных имен переменных также является критическим фактором удобочитаемости кода. И хотя такие автоматизированные инструменты, как Black, могут принимать синтаксические решения (например, выбирать число отступов в коде), они не спо- собны принимать семантические решения — скажем, насколько удачно выбрано имя переменной. За это отвечаете вы. Об этом мы поговорим в следующей главе.

4
Выбор понятных имен
«В программировании есть только две сложные проблемы — выбор имен, аннулирование кэша и ошибки смещения на единицу» — эта классическая шутка, приписываемая Леону
Бамбрику (Leon Bambrick) и основанная на высказывании
Фила Карлтона (Phil Karlton), содержит зерно истины: трудно придумать хорошие имена (формально называемые идентифи-
каторами) для переменных, функций, классов и вообще чего угодно в програм- мировании. Компактные, содержательные имена важны для удобочитаемости вашей программы. Тем не менее это проще сказать, чем сделать. Если вы переез- жаете в новый дом, можно пометить все коробки надписью «Барахло» — надпись компактная, но не содержательная. Название книги по программированию «Как создавать собственные компьютерные игры на языке Python» — содержательное, но не компактное.
Если вы пишете не «одноразовый» код, который вы не собираетесь сопровождать после однократного запуска программы, вам стоит подумать над выбором хороших имен в вашей программе. Предположим, вы просто присвоили переменным имена a
, b
и c
, значит, вам в будущем придется потратить лишние усилия, чтобы запомнить, для чего предназначались эти переменные.
Выбор имен — субъективный выбор, который делаете именно вы. Автоматизи- рованные средства форматирования (такие как Black из главы 3) не способны решить, как должны называться ваши переменные. В этой главе я расскажу, как выбрать «хорошие» имена и избегать «плохих». Как обычно, мои рекомендации не высечены в камне; руководствуйтесь здравым смыслом, чтобы решить, когда стоит применять их в вашем коде.

86
Глава 4.Выбор понятных имен
МЕТАСИНТАКСИЧЕСКИЕ ПЕРЕМЕННЫЕ
Метасинтаксические переменные обычно используются в учебниках или фраг- ментах кода, когда необходимо обобщенное имя переменной. В Python в тех переменных, для которых имена несущественны, часто используют имена spam, eggs, bacon и ham. По этой причине я применяю их в примерах кода в книге, но не берите их для реальных программ. Имена происходят из скетча «Спам» группы Monty Python (https://en.wikipedia.org/wiki/Spam_(Monty_Python)).
Метасинтаксическим переменным также часто присваивают имена foo и bar.
Они происходят от сленгового сокращения FUBAR, которое использовали солдаты армии США во времена Второй Мировой войны, когда хотели со- общить, что ситуация «[уделана] до полной неузнаваемости».
Схемы регистра имен
Так как в идентификаторах Python различается регистр символов и они не могут содержать пробельные символы, программисты используют несколько схем в иден- тификаторах, состоящих из нескольких слов.
Змеиный регистр (
snake_case
) разделяет слова символом подчеркивания, который напоминает ползущую между словами змею. В этом случае все буквы записываются в нижнем регистре, а константы часто записываются в верхнем змеином регистре (
UPPER_SNAKE_CASE
).
Верблюжий регистр (
camelCase
) — слова записываются в нижнем регистре, но второе и следующие слова начинаются с заглавной. Эта схема в большин- стве случаев подразумевает, что первое слово начинается с буквы нижнего регистра. Буквы верхнего регистра напоминают верблюжьи горбы.
Схема Pascal (
PascalCase
) — названа так, потому что применяется в языке программирования Pascal; аналогична схеме верблюжьего регистра, но первое слово в ней тоже начинается с заглавной.
Выбор регистра относится к области форматирования кода, об этом я рассказывал в главе 3. На практике чаще всего встречаются змеиный и верблюжий регистры. Вы можете использовать любую схему, но в одном проекте — только одну, а не обе сразу.
Соглашения об именах PEP 8
В документе PEP 8 (глава 3) приведены некоторые правила формирования имен в Python.

Длина имен
87
Все буквы должны быть буквами ASCII — то есть латинскими буквами верхнего и нижнего регистров без диакритических знаков.
Имена модулей должны быть короткими и состоять только из букв нижнего регистра.
Имена классов необходимо записывать в схеме Pascal.
Имена констант следует записывать в верхнем змеином регистре.
Имена функций, методов и переменных записывают в нижнем змеином регистре.
Первый аргумент методов всегда должен называться self в нижнем регистре.
Первый аргумент методов классов всегда должен называться cls в нижнем регистре.
Приватные атрибуты классов всегда начинают с символа подчеркивания (
_
).
Публичные атрибуты классов никогда не начинают с символа подчеркива- ния (
_
).
При необходимости вы можете изменять или нарушать эти правила. Например, хотя английский язык доминирует в программировании, в идентификаторах можно использовать символы любых языков: команда コンピューター
=
'laptop'
является синтаксически действительным кодом Python. Как вы видите, мои предпочтения в области имен переменных противоречат PEP 8, потому что я использую верблю- жий регистр вместо змеиного. PEP 8 содержит напоминание о том, что программист не обязан неуклонно следовать PEP 8. Важнейший фактор удобочитаемости — не выбор схемы, а последовательность в применении этой схемы.
С разделом «Naming Conventions» документа PEP 8 можно ознакомиться по адресу
https://www.python.org/dev/peps/pep-0008/#naming-conventions.
Длина имен
Очевидно, имена не должны быть слишком короткими или слишком длинными.
Длинные имена переменных утомительно вводить, а короткие могут быть непонят- ными или дезинформирующими. Но так как код читают чаще, чем пишут, лучше все-таки задавать более длинные имена переменных. Рассмотрим примеры.
Слишком короткие имена
Самая распространенная ошибка при выборе имен — суперкороткие имена. Они зачастую кажутся вам понятными, когда вы впервые их записываете, но вы можете забыть их точный смысл через несколько дней или недель. Рассмотрим несколько разновидностей коротких имен.

88
Глава 4.Выбор понятных имен
Одно- или двухбуквенное имя (например, g
), вероятно, обозначает какое-то слово, начинающееся с этой буквы, но таких слов очень много. Сокращения и одно-двухбуквенные имена легко записать, но они плохо читаются. Это замечание относится и к следующему пункту.
Сокращенные имена вида mon
— могут означать monitor, month, monster и множество других слов.
Имя из одного слова — например, start
(начало) — может трактоваться по- разному: начало чего? При отсутствии уточнения другие люди вас вряд ли поймут.
Одно- и двухбуквенные имена, сокращения или однословные имена могут быть понятны вам, но всегда следует помнить, что другие программисты (или же вы сами через несколько недель) вряд ли поймут их смысл.
В отдельных случаях короткие имена переменных вполне допустимы. Например, имя i
часто используется с переменными циклов for
, перебирающих диапазоны чисел или индексов списка, а j
и k
(следующие за i
в алфавитном порядке) ис- пользуются с вложенными циклами:
>>>