Как писать красивый код с PEP 8. Часть #2⁠⁠

Первая часть: https://pikabu.ru/story/kak_pisat_krasivyiy_kod_s_pep_8_chas...

Отступы

«Должен быть один - и желательно только один - очевидный способ сделать это» (с) Дзен Python

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

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

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

Ключевыми правилами отступления, изложенными в PEP 8, являются:

- Используйте 4 последовательных пробела для обозначения отступа.

- Предпочтительнее использовать пробелы, чем табуляцию.

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

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

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

$ python2 -t code.py

Результат: Непоследовательное использование табуляции и пробелов в отступе

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

$ python2 -tt code.py

Ошибка табуляции: Непоследовательное использование табуляции и пробелов в отступе

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

$ python3 code.py

Ошибка табуляции: Непоследовательное использование табуляции и пробелов в отступе

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

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

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

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

В этом случае PEP 8 предоставляет две альтернативы для улучшения читаемости:

1. Добавьте комментарий после окончательного условия. Из-за подсветки синтаксиса в большинстве редакторов это отделяет условия от вложенного кода:

2. Добавьте дополнительный отступ на продолжение строки:

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

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

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

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

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

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

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

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

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

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

Комментарии

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

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

1. Ограничьте длину строки комментариев и строк документации до 72 символов.

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

3. Не забудьте обновить комментарии, если вы измените свой код.

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

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

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

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

2. Начните каждую строку с #, за которым следует один пробел.

3. Разделите абзацы строкой, содержащей один #.

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

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

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


Однострочные комментарии

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

1. Используйте однострочные комментарии экономно.

2. Напишите однострочный комментарии в той же строке, что и утверждение, к которому они относятся.

3. Отделяйте однострочные комментарии двумя или более пробелами от оператора.

4. Начните встроенные комментарии с # и одного пробела, как блочные комментарии.

5. Не используйте их, чтобы объяснить очевидное.

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

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

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

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

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

Докуменирующие строки

Докуменирующие строки - это строки, заключенные в двойные (" " ") или одинарные (' ' ') кавычки, которые ставятся в первой строке любой функции, класса, метода или модуля. Вы можете использовать их для объяснения и документирования конкретного блока кода. Существует целый PEP, PEP 257, который охватывает документирующие строки.

Наиболее важные правила, применяемые к этим видам строк:

1. Окружите документирующие строки тремя двойными кавычками с каждой стороны:  """Это строка документации""".

2. Напишите их для всех общедоступных модулей, функций, классов и методов.

3. Поместите """, который завершает многострочную строку документации, на закрывающуюся строку:

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

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

Оригинал статьи: https://realpython.com/python-pep8/

Все права принадлежат авторам статьи (команде Real Python).

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

Спасибо за внимание!

P.S. Прощу прощения за задержку, выдалась тяжелая сессия :)
P.S.S. Приветствуется адекватная критика и пожелания на следующий перевод.