В борьбе за красивый и понятный код Python-сообществу нужны ориентиры: что такое хорошо и что такое плохо. Создатель языка Гвидо ван Россум (Guido van Rossum) и его соратник Барри Уорсо (Barry Warsaw) описали хороший стиль Py-кода в документе PEP 8.

Каждый уважающий себя питонист обязан знать этот стандарт. Читайте оригинал или перевод, главное  —  вдумчиво!

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

Зачем нужен PEP 8

Единый стиль оформления делает код понятным для самого программиста и его коллег с разным уровнем подготовки.

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

• 
• Гвидо ван Россум
• PEP 8 затрагивает структуру и внешний вид кода:

• выбор кодировки исходного кода;
• группировку инструкций по импорту модулей;
• максимальную длину строки кода  —  рекомендуется до 79 знаков, а для строк документации (docstring)  — 72 знака;
• использование отступов  —  табуляции и пробелов;
• использование пустых строк для разбивки кода на блоки и выделения функций верхнего уровня;
• использование комментариев;
• именование переменных, констант, классов и экземпляров, функций, аргументов, модулей, пакетов;
• выбор уровня доступности классов и методов  (public, private, API-подклассы), а также порядка их наследования.

Пишете ли вы код в PyCharm, Notepad++ или другом редакторе, сохранять .py-файлы лучше в кодировке UTF-8.

Для Python 3 она рекомендована официально, для Python 2 формально требуется кодировка ASCII, но она не поддерживает кириллицу, поэтому для приложений на русском разумно использовать ту же UTF-8.

Если по какой-то причине вам очень нужна «альтернативная» кодировка исходника, обязательно укажите её в комментарии в первой строке файла:

# coding: cp1251 print(«Текст в кодировке Windows 1251.») input()

Без этого интерпретатор выдаст ошибку.

PEP 8: Питону важны отступы

Самое известное требование PEP 8 по оформлению Python-кода — отступы. С их помощью задают структуру условий, циклов, функций. Традиционно на один уровень отступа ставят четыре пробела. Например:

if sunny: print(«The sun is shining!») else: pass

Теоретически вы можете использовать иное число пробелов: 2, 8 и т.д. Главное, чтобы оно совпадало по всему коду —  иначе интерпретатор будет ругаться. Но 4  —  «золотой стандарт» сообщества: быстро ставить, привычно читать.

В чужом коде вам может встретиться другой вид отступа — табуляция. Его PEP 8 категорически не рекомендует, но с одной оговоркой. Если вы дорабатываете готовый проект, где отступы сделаны табуляцией, придерживайтесь принятого до вас стандарта. Если в коде разнобой, замените всё на пробелы.

Интересный факт: исследование 2017 года на Stack Overflow показало, что программисты, которые делают отступы пробелами, зарабатывают почти на 9% больше, чем любители Tab'а.

Когда пробелы в Python не ставят

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

2. Перед скобками при вызове аргумента. Неправильно: arg (1). Правильно: arg(1).

3. Перед скобками индекса и среза: dict['step'] = map[i].

4. Между именем параметра/аргумента, знаком «=» и значением: min(a=10, b=input).

И, пожалуйста,не выравнивайте код лишними пробелами. По сторонам от «=» ставьте не больше одного пробела. Не пытайтесь  с помощью отступов придать блоку вид таблицы или оглавления. Это замедляет чтение и понимание написанного.

Лучше ставьте по одному пробелу по сторонам от знаков арифметических действий:

x = (y + 1) * (y — a)

Не рекомендуется записывать несколько команд в одну строку через точку с запятой. Вместо «act1(); act2(); act3()»  —  пишите:

act1() act2() act3()

В х не забывайте ставить пробел после знака «#».

PEP 8 и имена объектов в Python

Если хотите назвать переменную одним символом, избегайте строчной латинской l («эль»), заглавной I («ай») и заглавной O — в некоторых шрифтах они неотличимы от цифр 1 и 0 соответственно. С заглавной L таких проблем нет.

Объекты разного типа должны отличаться и по формату записи имён. Так читатель быстрее понимает, что перед ним. Называйте:

PEP 8: нейминг и размещение кода

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

В этой статье переходим к разбору конкретных рекомендаций по оформлению кода на Python.

Мы рассмотрим, как выбирать имена, как делать вертикальные и горизонтальные отступы в коде, как переносить строки, где ставить закрывающие скобки.

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

 «Явное лучше неявного», — Дзен Python.

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

Совет: никогда не используйте однобуквенные имена l, O или I, поскольку они могут быть ошибочно приняты за 1 и 0 при определённых шрифтах:

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

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

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

ТипСоглашение о наименованииПримеры

Функция	Используйте слово/слова в нижнем регистре. Отделяйте слова нижним подчёркиванием.	function, my_function
Переменная	Используйте одну букву, слово или слова в нижнем регистре. Для удобства чтения разделяйте слова нижним подчеркиванием.	x, var, my_variable
Класс	Каждое слово начинайте с заглавной буквы. Не разделяйте слова подчеркиванием. Этот стиль называется Pascal Case.	Model, MyClass
Метод	Используйте слово/слова в нижнем регистре. Для удобства чтения разделяйте слова подчеркиванием.	class_method, method
Константа	Используйте одну букву, слово или слова в верхнем регистре. Для удобства чтения разделяйте слова подчеркиванием.	CONSTANT, MY_CONSTANT, MY_LONG_CONSTANT
Модуль	Используйте короткое слово/слова в нижнем регистре. Для удобства чтения разделяйте слова подчеркиванием.	module.py, my_module.py
Пакет	Используйте короткие слова или слова в нижнем регистре. Не разделяйте слова подчеркиванием.	package, mypackage

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

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

[python_ad_block]

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

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

При именовании переменных у вас может возникнуть соблазн выбрать простые однобуквенные имена в нижнем регистре, например, 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() легко может быть сокращением от double. Но представьте, что вы вернетесь к этому коду через несколько дней. Возможно, вы забыли, чего пытались достичь с помощью этой функции, и из-за этого будет сложно угадать, как вы ее сократили.

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

# Рекомендуется
def multiply_by_two(x):
return x * 2

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

Размещение кода

 «Красивое лучше уродливого», — Дзен 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. Но всё же рекомендуется первый вариант.

Отступы

 «Должен быть один – и желательно только один – очевидный способ сделать что-либо», — Дзен Python.

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

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

x = 3
if x > 5:
print('x больше 5')

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

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

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

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

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

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

$ python2 -t code.py
code.py: inconsistent use of tabs and spaces in indentation

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

$ python2 -tt code.py
File «code.py», line 3
print(i, j)
^
TabError: inconsistent use of tabs and spaces in indentation

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

$ python3 code.py
File «code.py», line 3
print(i, j)
^
TabError: inconsistent use of tabs and spaces in indentation

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

Отступ после разрывов строки

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

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

def function(arg_one, arg_two,
arg_three, arg_four):
return arg_one

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

x = 5
if (x > 3 and
x < 10): print(x)

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

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

x = 5
if (x > 3 and
x < 10): # Оба условия соблюдены print(x)

Во-вторых, можно сделать дополнительный отступ в продолжении строки:

x = 5
if (x > 3 and
x < 10): print(x)

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

var = function(
arg_one, arg_two,
arg_three, arg_four)

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

# Не рекомендуется
var = function(arg_one, arg_two,
arg_three, arg_four)

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

# Не рекомендуется
def function(
arg_one, arg_two,
arg_three, arg_four):
return arg_one

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

def function(
arg_one, arg_two,
arg_three, arg_four):
return arg_one

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

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

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

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

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

Можно выровнять закрывающую скобку по первому не пробельному символу предыдущей строки:

list_of_numbers = [
1, 2, 3,
4, 5, 6,
7, 8, 9
]

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

list_of_numbers = [
1, 2, 3,
4, 5, 6,
7, 8, 9
]

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

Перевод части статьи How to Write Beautiful Python Code With PEP 8.

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

PEP 8 — the Style Guide for Python Code

This document gives coding conventions for the Python code comprising the standard library in the main Python distribution. Please see the companion informational PEP describing style guidelines for the C code in the C implementation of Python 1.

This document and PEP 257 (Docstring Conventions) were adapted from Guido’s original Python Style Guide essay, with some additions from Barry’s style guide 2.

This style guide evolves over time as additional conventions are identified and past conventions are rendered obsolete by changes in the language itself.

Many projects have their own coding style guidelines. In the event of any conflicts, such project-specific guides take precedence for that project.

A Foolish Consistency is the Hobgoblin of Little Minds

One of Guido’s key insights is that code is read much more often than it is written. The guidelines provided here are intended to improve the readability of code and make it consistent across the wide spectrum of Python code. As PEP 20 says, “Readability counts”.

A style guide is about consistency. Consistency with this style guide is important. Consistency within a project is more important. Consistency within one module or function is the most important.

However, know when to be inconsistent—sometimes style guide recommendations just aren't applicable. When in doubt, use your best judgment. Look at other examples and decide what looks best. And don’t hesitate to ask!

In particular: do not break backwards compatibility just to comply with this PEP!

Some other good reasons to ignore a particular guideline:

1. When applying the guideline would make the code less readable, even for someone who is used to reading code that follows this PEP.
2. To be consistent with surrounding code that also breaks it (maybe for historic reasons) – although this is also an opportunity to clean up someone else’s mess (in true XP style).
3. Because the code in question predates the introduction of the guideline and there is no other reason to be modifying that code.
4. When the code needs to remain compatible with older versions of Python that don’t support the feature recommended by the style guide.

Code lay-out

Use 4 spaces per indentation level.

Continuation lines should align wrapped elements either vertically using Python’s implicit line joining inside parentheses, brackets and braces, or using a hanging indent 3. When using a hanging indent the following should be considered; there should be no arguments on the first line and further indentation should be used to clearly distinguish itself as a continuation line.

Yes:

# Aligned with opening delimiter.
foo = long_function_name(var_one, var_two,
var_three, var_four)

# More indentation included to distinguish this from the rest.
def long_function_name(
var_one, var_two, var_three,
var_four):
print(var_one)

# Hanging indents should add a level.
foo = long_function_name(
var_one, var_two,
var_three, var_four)

No:

# Arguments on first line forbidden when not using vertical alignment.
foo = long_function_name(var_one, var_two,
var_three, var_four)

# Further indentation required as indentation is not distinguishable.
def long_function_name(
var_one, var_two, var_three,
var_four):
print(var_one)

The 4-space rule is optional for continuation lines.

Optional:

# Hanging indents *may* be indented to other than 4 spaces.
foo = long_function_name(
var_one, var_two,
var_three, var_four)

When the conditional part of an if-statement is long enough to require that it be written across multiple lines, it’s worth noting that the combination of a two character keyword (i.e. if), plus a single space, plus an opening parenthesis creates a natural 4-space indent for the subsequent lines of the multiline conditional.

This can produce a visual conflict with the indented suite of code nested inside the if-statement, which would also naturally be indented to 4 spaces. This PEP takes no explicit position on how (or whether) to further visually distinguish such conditional lines from the nested suite inside the if-statement.

Acceptable options in this situation include, but are not limited to:

# No extra indentation.
if (this_is_one_thing and
that_is_another_thing):
do_something()

# Add a comment, which will provide some distinction in editors
# supporting syntax highlighting.
if (this_is_one_thing and
that_is_another_thing):
# Since both conditions are true, we can frobnicate.
do_something()

# Add some extra indentation on the conditional continuation line.
if (this_is_one_thing
and that_is_another_thing):
do_something()

(Also see the discussion of whether to break before or after binary operators below.)

The closing brace/bracket/parenthesis on multi-line constructs may either line up under the first non-whitespace character of the last line of list, as in:

my_list = [
1, 2, 3,
4, 5, 6,
]
result = some_function_that_takes_arguments(
'a', 'b', 'c',
'd', 'e', 'f',
)

or it may be lined up under the first character of the line that starts the multi-line construct, as in:

my_list = [
1, 2, 3,
4, 5, 6,
]
result = some_function_that_takes_arguments(
'a', 'b', 'c',
'd', 'e', 'f',
)

Tabs or Spaces?

• Spaces are the preferred indentation method.
• Tabs should be used solely to remain consistent with code that is already indented with tabs.
• Python 3 disallows mixing the use of tabs and spaces for indentation.
• Python 2 code indented with a mixture of tabs and spaces should be converted to using spaces exclusively.

When invoking the Python 2 command line interpreter with the -t option, it issues warnings about code that illegally mixes tabs and spaces.

When using -tt these warnings become errors. These options are highly recommended!

Maximum Line Length

1. Limit all lines to a maximum of 79 characters.
2. For flowing long blocks of text with fewer structural restrictions (docstrings or comments), the line length should be limited to 72 characters.

3. Limiting the required editor window width makes it possible to have several files open side-by-side, and works well when using code review tools that present the two versions in adjacent columns.

The default wrapping in most tools disrupts the visual structure of the code, making it more difficult to understand.

The limits are chosen to avoid wrapping in editors with the window width set to 80, even if the tool places a marker glyph in the final column when wrapping lines. Some web based tools may not offer dynamic line wrapping at all.

Some teams strongly prefer a longer line length. For code maintained exclusively or primarily by a team that can reach agreement on this issue, it is okay to increase the nominal line length from 80 to 100 characters (effectively increasing the maximum length to 99 characters), provided that comments and docstrings are still wrapped at 72 characters.

The Python standard library is conservative and requires limiting lines to 79 characters (and docstrings/comments to 72).

The preferred way of wrapping long lines is by using Python’s implied line continuation inside parentheses, brackets and braces. Long lines can be broken over multiple lines by wrapping expressions in parentheses. These should be used in preference to using a backslash for line continuation.

Backslashes may still be appropriate at times. For example, long, multiple with-statements cannot use implicit continuation, so backslashes are acceptable:

with open('/path/to/some/file/you/want/to/read') as file_1,
open('/path/to/some/file/being/written', 'w') as file_2:
file_2.write(file_1.read())

• (See the previous discussion on multiline if-statements for further thoughts on the indentation of such multiline with-statements.)
• Another such case is with assert statements.
• Make sure to indent the continued line appropriately.

Should a line break before or after a binary operator?

For decades the recommended style was to break after binary operators. But this can hurt readability in two ways: the operators tend to get scattered across different columns on the screen, and each operator is moved away from its operand and onto the previous line. Here, the eye has to do extra work to tell which items are added and which are subtracted:

# No: operators sit far away from their operands
income = (gross_wages +
taxable_interest +
(dividends — qualified_dividends) —
ira_deduction —
student_loan_interest)

To solve this readability problem, mathematicians and their publishers follow the opposite convention. Donald Knuth explains the traditional rule in his Computers and Typesetting series:

“Although formulas within a paragraph always break after binary operations and relations, displayed formulas always break before binary operations” 4.

Following the tradition from mathematics usually results in more readable code:

# Yes: easy to match operators with operands
income = (gross_wages
+ taxable_interest
+ (dividends — qualified_dividends)
— ira_deduction
— student_loan_interest)

In Python code, it is permissible to break before or after a binary operator, as long as the convention is consistent locally. For new code Knuth's style is suggested.

Blank Lines

Surround top-level function and class definitions with two blank lines.

Method definitions inside a class are surrounded by a single blank line.

Extra blank lines may be used (sparingly) to separate groups of related functions. Blank lines may be omitted between a bunch of related one-liners (e.g. a set of dummy implementations).

Use blank lines in functions, sparingly, to indicate logical sections.

Python accepts the control-L (i.e. ^L) form feed character as whitespace; Many tools treat these characters as page separators, so you may use them to separate pages of related sections of your file. Note, some editors and web-based code viewers may not recognize control-L as a form feed and will show another glyph in its place.

Source File Encoding

1. Code in the core Python distribution should always use UTF-8 (or ASCII in Python 2).
2. Files using ASCII (in Python 2) or UTF-8 (in Python 3) should not have an encoding declaration.
3. In the standard library, non-default encodings should be used only for test purposes or when a comment or docstring needs to mention an author name that contains non-ASCII characters; otherwise, using x, u, U, or N escapes is the preferred way to include non-ASCII data in string literals.

PEP8: руководство по написанию чистого и читаемого кода на Python

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

Один из таких стандартов — PEP8, который устанавливает рекомендации по стилю и форматированию кода на языке Python.

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

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

PEP8 — это руководство по стилю кода для языка программирования Python. Он описывает рекомендации и правила для написания читаемого, понятного и консистентного кода на Python.

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

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

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

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

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

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

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

Например:

# Правильно:
if x == 1:
print(«x is 1»)

# Неправильно:
if x == 1:
print(«x is 1»)

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

Например:

# Правильно:
long_string = «This is a really long string that »
«spans multiple lines.»

# Неправильно:
long_string = «This is a really long string that spans multiple lines.»

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

Например:

# Правильно:
x = 2 + 3
y = (1 + 2) * 3

# Неправильно:
x=2+3
y = ( 1 + 2 ) * 3

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

Например:

Оформление кода Python — PEP 8: красивый код или как называть классы и переменные

Python имеет определенные стандарты кода, которым стараются следовать все программисты. Эти стандарты описаны в документации PEP8.

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

Почему важно стандартизировать код?

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

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

Рекомендации по созданию красивого кода на Python не определяют стиль кода полностью. Поэтому программист может делать некоторые вещи на своё усмотрение, однако он всё ещё должен следовать тем указаниям, которые определены в стандарте.

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

Разметка кода на Python

Этот раздел содержит указания, определяющие, как оформлять код на Python 3 (пробелы, отступы, строки).

Отступы

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

f1 = func(first_arg, second_arg,
third_arg, fourth_arg)

либо использовать четыре пробела, но с обязательным переносом первой строки:

f1 = func(
first_arg, second_arg,
third_arg, fourth_arg)
Использовать для продолжения именно 4 пробела — это не обязательное правило для строк продолжения перечисления. Можно использовать и другое количество пробелов, например, 2.

Если после списка аргументов следует еще какой-либо код (например, если это объявляется функция), то к отступу аргументов добавляется еще 4 пробела:

def func(
first_arg, second_arg,
third_arg, fourth_arg):
print(fourth_arg)

Это делается для того, чтобы отделить аргументы от тела функции.

В случае с оператором if, программист может как использовать, так и не использовать экстра отступы:

if(temp > 5 and
temp < 25): some_func(some_args[]) if(temp > 5
and temp < 25): some_func(some_args[])

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

Закрывающая конструкция в функции или структуре может располагаться под первым символом нижней строки:

names = [
«John», «Alex»,
«Olivia», «Jacob»,
]

Также её можно поместить в самое начало строки:

f = some_f(
«str1», «str2»,
«str3», «str4»,
)

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

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

PEP 8 — руководство по написанию кода на Python

Этот документ описывает соглашение о том, как писать код для языка python, включая стандартную библиотеку, входящую в состав python.

PEP 8 создан на основе рекомендаций Гуидо ван Россума с добавлениями от Барри. Если где-то возникал конфликт, мы выбирали стиль Гуидо. И, конечно, этот PEP может быть неполным (фактически, он, наверное, никогда не будет закончен).

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

Это руководство о согласованности и единстве. Согласованность с этим руководством очень важна. Согласованность внутри одного проекта еще важнее.

А согласованность внутри модуля или функции — самое важное. Но важно помнить, что иногда это руководство неприменимо, и понимать, когда можно отойти от рекомендаций.

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

Две причины для того, чтобы нарушить данные правила:

Используйте 4 пробела на каждый уровень отступа.

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

Правильно:

# Выровнено по открывающему разделителю
foo = long_function_name(var_one, var_two, var_three, var_four) # Больше отступов включено для отличения его от остальных
def long_function_name( var_one, var_two, var_three, var_four): print(var_one)

Неправильно:

# Аргументы на первой линии запрещены, если не используется вертикальное выравнивание
foo = long_function_name(var_one, var_two, var_three, var_four) # Больше отступов требуется, для отличения его от остальных
def long_function_name( var_one, var_two, var_three, var_four): print(var_one)

Опционально:

# Нет необходимости в большем количестве отступов.
foo = long_function_name( var_one, var_two, var_three, var_four)

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

my_list = [ 1, 2, 3, 4, 5, 6, ]
result = some_function_that_takes_arguments( 'a', 'b', 'c', 'd', 'e', 'f', )

либо быть под первым символом строки, начинающей многострочную конструкцию:

my_list = [ 1, 2, 3, 4, 5, 6,
]
result = some_function_that_takes_arguments( 'a', 'b', 'c', 'd', 'e', 'f',
)

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

Когда вы вызываете интерпретатор Python 2 в командной строке с параметром -t, он выдает предупреждения (warnings) при использовании смешанного стиля в отступах, а запустив интерпретатор с параметром -tt, вы получите в этих местах ошибки (errors). Эти параметры очень рекомендуются!

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

PEP 8 в Python – правила для идеального кода

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

Что такое PEP в Python?

PEP – это аббревиатура от Python Enterprise Proposal. Написание кода с правильной логикой является ключевым фактором программирования, но многие другие важные факторы могут повлиять на качество кода. Стиль кодирования разработчика делает код очень надежным, и каждый разработчик должен помнить, что Python строго следует порядку и формату строки.

Адаптивный красивый стиль кодирования делает код более читабельным. Код становится простым для конечного пользователя.

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

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

PEP 8 улучшает читаемость кода Python, но почему читаемость так важна? Давайте разберемся с этой концепцией.

Создатель Python Гвидо ван Россум сказал, что код может быть написан за несколько минут, несколько часов или целый день, но как только мы напишем код, мы больше никогда его не переписываем. Но иногда нам нужно читать код снова и снова.

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

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

Условные обозначения

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

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

Пример –

Одна строчная буква

a = 10

Одна заглавная буква

A = 10

Строчные буквы

var = 10

Строчные буквы с подчеркиванием

number_of_apple = 5

ВЕРХНИЙ РЕГИСТР

VAR = 6

ВЕРХНИЙ РЕГИСТР С ПОДЧЕРКИВАНИЕМ

NUM_OF_CARS =20

Заглавные слова(или CamelCase)

NumberOfBooks = 100

Примечание. При использовании сокращений в CapWords делайте все буквы сокращения заглавными. Таким образом, HTTPServerError лучше, чем HttpServerError.

Стили имен

Ниже приведена таблица, в которой указаны некоторые из распространенных стилей именования в Python. Рассмотрим следующую таблицу.

Тип
Соглашение об именовании
Примеры

Функция	Мы должны использовать слова в нижнем регистре или разделять слова подчеркиванием.	myfunction, my_function
Переменная	Мы должны использовать строчные буквы, слова или отдельные слова, чтобы улучшить читаемость.	a, var, variable_name
Класс	Первая буква названия класса должна быть заглавной; используйте camel case. Не разделяйте слова подчеркиванием.	MyClass, Form, Model
Метод	Мы должны использовать строчные буквы, слова или отдельные слова, чтобы улучшить читаемость.	class_method, method
Константа	Использование  заглавных букв, слов или отдельных слов для повышения удобочитаемости.	MYCONSTANT, CONSTANT, MY_CONSTANT
Модуль	Мы должны использовать строчные буквы, слова или отдельные слова, чтобы улучшить читаемость.	Module_name.py, module.py
Пакет	Мы должны использовать строчные буквы, слова или отдельные слова, чтобы улучшить читаемость. Не разделяйте слова подчеркиванием.	package, mypackage

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

Макет кода

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

Отступ

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

x = 5
if x == 5:
print('x is larger than 5')

В приведенном выше примере оператор печати с отступом будет выполнен, если условие оператора if истинно. Этот отступ определяет блок кода и сообщает нам, какие операторы выполняются при вызове функции или триггере условия.

Вкладки против пробела

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

Отступ после разрыва строки

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

Пример –

# Correct Way:

# Aligned with opening delimiter.
obj = func_name(argument_one, argument_two,
argument_three, argument_four

Мы можем использовать следующую структуру.

# first line doesn't has any argument
# We add 4 spaces from the second line to discriminate arguments from the rest.
def function_name(
argument_one, argument_two, argument_three,
argument_four):
print(argument_two)

# 4 space indentation to add a level.
foo = long_function_name(
var_one, var_two,
var_three, var_four)

Использование документационной строки

Python предоставляет два типа документационных строк – однострочные и многострочные. Мы используем тройные кавычки для определения однострочного или многострочного типа. В основном они используются для описания функции или конкретной программы. Давайте разберемся в следующем примере.

def add(a, b):
«»»This is simple add method»»»

«»»This is
a
simple add program to add
the two numbers. «»»

Должна ли линия разрываться до или после бинарного оператора?

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

Пример –

# Wrong:
# operators sit far away from their operands
marks =(engilsh_marks +
math_marks +
(science_marks — biology_marks) +
Physics_marks

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

Пример –

# Correct:
# easy to match operators with operands
Total_marks =(English_marks
+ math_marks
+(science_marks — biology_marks)
+ physics_marks

Python позволяет нам разбивать строку до или после бинарного оператора, если соглашение согласовано локально.

Модуль импорта

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

import pygame
import os
import sys

Неверно

import sys, os

Мы также можем использовать следующий подход.

from subprocess import Popen, PIPE

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

import mypkg.sibling
from mypkg import sibling
from mypkg.sibling import example

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

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

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

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

class FirstClass:
pass

class SecondClass:
pass

def main_function():

return None

• Одна пустая строка внутри классов – функции, которые мы определяем в классе, связаны друг с другом. Давайте посмотрим на следующий пример –

class FirstClass:
def method_one(self):
return None

def second_two(self):
return None

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

def cal_variance(n_list):
list_sum = 0
for n in n_list:
list_sum = list_sum + n
mean = list_sum / len(n_list)

square_sum = 0
for n in n_list:
square_sum = square_sum + n**2
mean_squares = square_sum / len(n_list)

return mean_squares — mean**2

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

Закрывающие скобки

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

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

list_numbers = [
5, 4, 1,
4, 6, 3,
7, 8, 9
]

• Совместите закрывающие фигурные скобки с первым символом строки.

list_numbers = [
5, 4, 1,
4, 6, 3,
7, 8, 9
]

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