iCleverer

Отступы

«Должен быть один - и желательно только один - очевидный способ сделать это» (с) Дзен 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. Приветствуется адекватная критика и пожелания на следующий перевод.

PEP 8 (иногда PEP8 или PEP-8) - документ, который содержит набор рекомендаций и практик, про то, как писать на Python. Написан в 2001 Гуидо ван Россумом, Барри Уорсо и Ником Когхланом. Основной целью PEP 8 является улучшение читаемости и согласованности кода.

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

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

К концу этой статьи, вы сможете:

* Написать код Python, соответствующий PEP 8

* Понять обоснование руководящих принципов, изложенных в PEP 8

* Настроить среду разработки так, чтобы вы могли начинать писать Python код, совместимый с PEP 8

Почему нам нужен PEP 8

Читаемость имеет значение. (c) Дзен Python

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

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

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

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

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

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

Явное лучше, чем неявное (с) Дзен Python

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

Примечание. Никогда не используйте однобуквенные имена l (прим: строчное L), O или I (прим: прописное i), поскольку их можно принять за 1 и 0, в зависимости от гарнитуры:

O = 2 # Это может выглядеть так, будто вы пытаетесь переопределить ноль, как число два

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

Функции - используйте строчное слово(-а). Разделяйте слова нижним подчеркиванием для улучшения читаемости. Например: function, my_function

Переменные - используйте строчную букву, слово или слова. Разделяйте слова нижним подчеркиванием, чтобы улучшить читаемость. Например: x, var, my_variable

Классы - начинайте каждое слово с заглавной буквы. Не разделяйте слова подчеркиванием. Этот стиль называется ВерблюжийРегистр (прим: чаще всего употребляется всё же английский вариант названия: кэмэл кейс). Например: Model, MyClass

Методы - используйте строчные слова или слова. Разделяйте слова нижним подчеркиванием, чтобы улучшить читаемость. Например: class_method, method

Константы - используйте заглавные буквы, слово или слова. Разделяйте слова подчеркиванием, чтобы улучшить читаемость. (прим: в Python нет отдельного типа для констант. А так как в Python существует благодаря тому, что есть много соглашений, которые должны соблюдаться разработчиками. Поэтому и используется данное обозначение для констант. ) Например: CONSTANT, MY_CONSTANT, MY_LONG_CONSTANT

Модули - используйте короткое строчное слово(-а). Разделяйте слова нижним подчеркиванием, чтобы улучшить читаемость. Например: module.py, my_module.py

Пакеты - используйте короткое строчное слово(-а). Не разделяйте слова подчеркиванием. Например: package, mypackage

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

Как выбрать имена

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

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

# Не рекомендуется

x = 'John Smith'

y, z = x.split()

print(z, y, sep=', ')

'Smith, John'

Это будет работать, но вы должны будете отслеживать, что представляют собой x, y и z. Это также может сбивать с толку соавторов. Более ясный выбор имен представляет из себя что-то вроде этого:

# Рекомендовано

name = 'John Smith'

first_name, last_name = name.split()

print(last_name, first_name, sep=', ')

'Smith, John'

Точно так же, чтобы уменьшить количество набираемого текста, может возникнуть соблазн использовать сокращения при выборе имен. В приведенном ниже примере мы определили функцию db (), которая принимает один аргумент x и удваивает его:

# Не рекомендуется

def db(x):

return x * 2

На первый взгляд это может показаться разумным выбором. db () может легко быть сокращением для удвоения. Но представьте, что вы вернетесь к этому коду через несколько дней. Возможно, вы забудете, что хотели сделать с помощью этой функции, и это затруднило бы возможность понять, как вы сокращали ее.

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

# Рекомендовано

def multiply_by_two(x):

return x * 2

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

Макет кода

Красиво лучше, чем некрасиво. (c) Дзен Python

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

Пустые линии

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

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

class MyFirstClass:

pass

class MySecondClass:

pass

def top_level_function():

return None

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

class MyClass:

def first_method(self):

return None

def second_method(self):

return None

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

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

def calculate_variance(number_list):

sum_list = 0

for number in number_list:

sum_list = sum_list + number

mean = sum_list / len(number_list)

sum_squares = 0

for number in number_list:

sum_squares = sum_squares + number**2

mean_squares = sum_squares / len(number_list)

return mean_squares - mean**2

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

PEP 8 предполагает, что строки должны быть ограничены 79 символами. Это позволяет открывать несколько файлов рядом друг с другом, а также избегать переноса строк.

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

Python примет продолжение строки, если код содержится в круглых, квадратных и фигурных скобках:

def function(arg_one, arg_two,

arg_three, arg_four):

return arg_one

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

from mypkg import example1, \

example2, example3

Однако, если вы можете использовать подразумеваемое продолжение, то вам следует всё же использовать продолжение.

Если разрыв строки должен происходить вокруг бинарных операторов, таких как + и *, это должно происходить перед оператором. Это правило вытекает из математики. Математики сходятся во мнении, что разрыв перед двоичными операторами улучшает читаемость. Сравните следующие два примера.

Ниже приведен пример разрыва перед бинарным оператором:

# Рекомендовано

total = (first_variable

+ second_variable

- third_variable)

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

Теперь давайте рассмотрим пример разрыва после бинарного оператора:

# Не рекомендовано

total = (first_variable +

second_variable -

third_variable)

Здесь сложнее увидеть, какая переменная добавляется, а какая вычитается.

Прерывание перед бинарными операторами создает более читаемый код, поэтому PEP 8 поощряет это. Код, который постоянно ломается после бинарного оператора, по-прежнему соответствует PEP 8. Тем не менее, вам рекомендуется разрывать перед двоичным оператором.

В следующей части рассмотрим отступы и как правильно комментировать код.

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

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

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