Pep 8 руководство по написанию кода на python на русском

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

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

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

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

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

1. Когда применение правила сделает код менее читаемым даже для того, кто привык читать код, который следует правилам.
2. Чтобы писать в едином стиле с кодом, который уже есть в проекте и который нарушает правила (возможно, в силу исторических причин) — впрочем, это возможность переписать чужой код.

# Выровнено по открывающему разделителю
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',
)

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())

class Rectangle(Blob):

    def __init__(self, width, height,
                 color='black', emphasis=None, highlight=0):
        if (width == 0 and height == 0 and
                color == 'red' and emphasis == 'strong' or
                highlight > 100):
            raise ValueError("sorry, you lose")
        if width == 0 and height == 0 and (color == 'red' or
                                           emphasis is None):
            raise ValueError("I don't think so -- values are %s, %s" %
                             (width, height))
        Blob.__init__(self, width, height,
                      color, emphasis, highlight)

x = x + 1                 # Increment x

x = x + 1                 # Компенсация границы

__version__ = "$Revision: 1a40d4eaa00b $"
# $Source$

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

Один из таких стандартов — 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

Именование

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

Например:

# Правильно:
age = 25
name = "John"

def calculate_sum(numbers):
    return sum(numbers)

# Неправильно:
a = 25
b = "John"

def calc_sum(nums):
    return sum(nums)

Комментарии

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

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

Например:

# Правильно:
# Получаем текущую дату и время
current_time = datetime.datetime.now()

# Неправильно:
current_time = datetime.datetime.now()  # Получаем текущую дату и время

Импорты

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

Например:

# Правильно:
import datetime
import os

from math import sqrt

import requests

# Неправильно:
import requests, os, datetime

from math import *

import my_module

Пробелы вокруг операторов

Используйте пустые строки для разделения логически связанных частей кода. Не используйте несколько операторов на одной строке.

Используйте пробелы вокруг операторов (=, +, -, *, /, //, %, и т. д.), но не используйте пробелы вокруг символа индексирования или среза.

Например:

# Правильно:
x = 2 + 3
y = x * 4
z = list[0]

# Неправильно:
x=2+3
y = x*4
z = list [0]

Названия функций и методов

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

Например:

# Правильно:
def calculate_sum(numbers):
    return sum(numbers)

def get_user_name(user):
    return user.name

# Неправильно:
def numbersSum(nums):
    return sum(nums)

def user(user):
    return user.name

Название переменных

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

Например:

# Правильно:
total_sum = 0
list_of_numbers = [1, 2, 3, 4]
user_name = "John"

# Неправильно:
t = 0
n = [1, 2, 3, 4]
un = "John"

Расположение функций и классов

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

Например:

# Правильно:
def calculate_sum(numbers):
    return sum(numbers)

def main():
    list_of_numbers = [1, 2, 3, 4]
    total_sum = calculate_sum(list_of_numbers)
    print(f"The total sum is: {total_sum}")

if __name__ == "__main__":
    main()

# Неправильно:
def main():
    list_of_numbers = [1, 2, 3, 4]
    total_sum = calculate_sum(list_of_numbers)
    print(f"The total sum is: {total_sum}")

def calculate_sum(numbers):
    return sum(numbers)

if __name__ == "__main__":
    main()

Длина строки

Строки не должны быть длиннее 79 символов. Если строка слишком длинная, ее можно разбить на несколько строк, используя скобки, запятые или операторы конкатенации.

Например:

# Правильно:
message = "This is a very long message that should be split " \
          "into multiple lines for better readability."

total_sum = (100 + 200 + 300 +
             400 + 500 + 600)

# Неправильно:
message = "This is a very long message that should be split into multiple lines for better readability."

total_sum = 100 + 200 + 300 + 400 + 500 + 600

Тройные кавычки

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

Например:

# Правильно:
def calculate_sum(numbers):
    """
    This function calculates the sum of the numbers in the given list.

    Parameters:
        numbers (list): A list of numbers to calculate the sum of.

    Returns:
        float: The sum of the numbers in the list.
    """
    return sum(numbers)

# Неправильно:
def calculate_sum(numbers):
    # This function calculates the sum of the numbers in the given list.
    return sum(numbers)

Полезные инструменты

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

Линтеры — это инструменты, которые анализируют код и проверяют его соответствие стандартам PEP8. Они предупреждают разработчиков о нарушениях стандартов PEP8 и других проблемах в их коде. Некоторые из наиболее популярных линтеров для Python включают:

• pylint — это линтер для Python, который проверяет соответствие кода стандартам PEP8. Он также обнаруживает другие проблемы в коде, такие как синтаксические ошибки, неиспользуемые переменные и дублирование кода.
• flake8 — это линтер, который проверяет соответствие кода стандартам PEP8, а также обнаруживает другие проблемы в коде, такие как неиспользуемые импорты и неправильное форматирование строк.
• PyCharm — это IDE для Python, которая включает встроенный линтер, который проверяет соответствие кода стандартам PEP8 и другие проблемы в коде. Он также предлагает рекомендации по исправлению нарушений стандартов PEP8.

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

1. Black — это автоматический форматировщик кода на Python, который форматирует код в соответствии со стандартами PEP8. Он удаляет неоднозначность в коде и делает его более понятным.
2. autopep8 — это инструмент, который автоматически форматирует код в соответствии со стандартами PEP8. Он также может исправлять другие проблемы в коде, такие как синтаксические ошибки.
3. YAPF — это автоматический форматировщик кода на Python, который форматирует код в соответствии со стандартами PEP8 и другими рекомендациями по стилю кодирования.

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

Кроме того, многие инструменты интегрируются с популярными средами разработки, такими как PyCharm и VS Code, что упрощает их использование и интеграцию в рабочий процесс разработки.

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

Дополнительные источники

Существует множество ресурсов и инструментов для дополнительного изучения PEP8 и его реализации в проектах.

Некоторые из них перечислены ниже:

• Официальный документ PEP8: Документ PEP8 можно найти на официальном сайте Python. Он содержит все основные правила и рекомендации по написанию чистого и понятного кода на Python.
• Flake8: Flake8 — это инструмент статического анализа кода на Python, который проверяет соответствие кода стандартам PEP8. Он также проверяет синтаксические ошибки, использование необъявленных переменных и другие нарушения.
• PyCharm: PyCharm — это интегрированная среда разработки (IDE) для Python, которая имеет встроенный инструмент PEP8. Он предупреждает вас, если ваш код нарушает стандарты PEP8, и предлагает исправления.
• Black: Black — это автоматический форматтер кода на Python, который следует стандартам PEP8. Он автоматически форматирует ваш код, чтобы он соответствовал стандартам PEP8, и также может использоваться для автоматического форматирования кода в больших проектах.
• pylint: pylint — это еще один инструмент статического анализа кода на Python, который проверяет соответствие кода стандартам PEP8. Он также предупреждает вас об использовании устаревших или небезопасных конструкций в вашем коде.
• Real Python: Real Python — это онлайн-платформа для изучения Python, которая содержит множество статей, учебных пособий и видеоуроков. Они предлагают руководства по написанию чистого и понятного кода на Python в соответствии с PEP8.
• Python Code Quality Authority: Python Code Quality Authority — это организация, которая управляет несколькими инструментами для проверки качества кода на Python, включая Flake8 и pylint. Они также поддерживают ряд стандартов и рекомендаций для написания чистого и понятного кода на Python.

Заключение

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

Одно утверждение на строку 

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

Плохо

print 'one'; print 'two'

if x == 1: print 'one'

if <complex comparison> and <other complex comparison>:
    # do something

Хорошо

print 'one'
print 'two'

if x == 1:
    print 'one'

cond1 = <complex comparison>
cond2 = <other complex comparison>
if cond1 and cond2:
    # do something

def complex_function(a, b, c):
    if not a:
        return None  # Raising an exception might be better
    if not b:
        return None  # Raising an exception might be better
    # Some complex code trying to compute x from a, b and c
    # Resist temptation to return x if succeeded
    if not x:
        # Some Plan-B computation of x
    return x  # One single exit point for the returned value x will help
              # when maintaining the code.

for index, item in enumerate(some_list):
    # do something with index and item

a, b = b, a

a, (b, c) = 1, (2, 3)

a, *rest = [1, 2, 3]
# a = 1, rest = [2, 3]
a, *middle, c = [1, 2, 3, 4]
# a = 1, middle = [2, 3], c = 4

filename = 'foobar.txt'
basename, __, ext = filename.rpartition('.')

four_nones = [None] * 4

four_lists = [[] for __ in xrange(4)]

letters = ['s', 'p', 'a', 'm']
word = ''.join(letters)

s = set(['s', 'p', 'a', 'm'])
l = ['s', 'p', 'a', 'm']

def lookup_set(s):
    return 's' in s

def lookup_list(l):
    return 's' in l

>>> import this
The Zen of Python, by Tim Peters

Beautiful is better than ugly.
Explicit is better than implicit.
Simple is better than complex.
Complex is better than complicated.
Flat is better than nested.
Sparse is better than dense.
Readability counts.
Special cases aren't special enough to break the rules.
Although practicality beats purity.
Errors should never pass silently.
Unless explicitly silenced.
In the face of ambiguity, refuse the temptation to guess.
There should be one-- and preferably only one --obvious way to do it.
Although that way may not be obvious at first unless you're Dutch.
Now is better than never.
Although never is often better than *right* now.
If the implementation is hard to explain, it's a bad idea.
If the implementation is easy to explain, it may be a good idea.
Namespaces are one honking great idea -- let's do more of those!

if attr == True:
    print 'True!'

if attr == None:
    print 'attr is None!'

# Just check the value
if attr:
    print 'attr is truthy!'

# or check for the opposite
if not attr:
    print 'attr is falsey!'

# or, since None is considered false, explicitly check for it
if attr is None:
    print 'attr is None!

d = {'hello': 'world'}
if d.has_key('hello'):
    print d['hello']    # prints 'world'
else:
    print 'default_value'

d = {'hello': 'world'}

print d.get('hello', 'default_value') # prints 'world'
print d.get('thingy', 'default_value') # prints 'default_value'

# Or:
if 'hello' in d:
    print d['hello']

# needlessly allocates a list of all (gpa, name) entires in memory
valedictorian = max([(student.gpa, student.name) for student in graduates])

valedictorian = max((student.gpa, student.name) for student in graduates)

def make_batches(items, batch_size):
    """
    >>> list(make_batches([1, 2, 3, 4, 5], batch_size=3))
    [[1, 2, 3], [4, 5]]
    """
    current_batch = []
    for item in items:
        current_batch.append(item)
        if len(current_batch) == batch_size:
            yield current_batch
            current_batch = []
    yield current_batch

[print(x) for x in sequence]

for x in sequence:
    print(x)

# Filter elements greater than 4
a = [3, 4, 5]
for i in a:
    if i > 4:
        a.remove(i)

while i in a:
    a.remove(i)

# comprehensions create a new list object
filtered_values = [value for value in sequence if value != x]

# generators don't create another list
filtered_values = (value for value in sequence if value != x)

# replace the contents of the original list
sequence[::] = [value for value in sequence if value != x]

# Add three to all list members.
a = [3, 4, 5]
b = a                     # a and b refer to the same list object

for i in range(len(a)):
    a[i] += 3             # b[i] also changes

a = [3, 4, 5]
b = a

# assign the variable "a" to a new list without changing "b"
a = [i + 3 for i in a]

a = [3, 4, 5]
for i, item in enumerate(a):
    print i, item
# prints
# 0 3
# 1 4
# 2 5

f = open('file.txt')
a = f.read()
print a
f.close()

with open('file.txt') as f:
    for line in f:
        print line

my_very_big_string = """For a long time I used to go to bed early. Sometimes, \
    when I had put out my candle, my eyes would close so quickly that I had not even \
    time to say “I’m going to sleep.”"""

from some.deep.module.inside.a.module import a_nice_function, another_nice_function, \
    yet_another_nice_function

my_very_big_string = (
    "For a long time I used to go to bed early. Sometimes, "
    "when I had put out my candle, my eyes would close so quickly "
    "that I had not even time to say “I’m going to sleep.”"
)

from some.deep.module.inside.a.module import (
    a_nice_function, another_nice_function, yet_another_nice_function)

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

Выше приведены некоторые общие соглашения об именах, которые можно использовать для улучшения кода 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 
] 

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

Комментарии

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

• Начните с заглавной буквы и напишите полное предложение.
• Обновите комментарий в случае изменения кода.
• Ограничьте длину строки комментариев и строк документации 72 символами.

Блочный комментарий

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

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

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

Посмотрим на следующий код.

 
for i in range(0, 5): 
    # Loop will iterate over i five times and print out the value of i 
    # new line character 
    print(i, '\n') 

Мы можем использовать больше абзаца для технического кода.

Встроенные комментарии

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

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

Ниже приведен пример встроенных комментариев.

 
a = 10    # The a is variable that holds integer value. 

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

 
x = 'Peter Decosta' #This is a student name 

Мы можем использовать следующее соглашение об именах.

 
Student_name = 'Peter Decosta' 

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

Излишнее добавление пробелов

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

Посмотрим на следующий пример.

Пример – 1

 
# Recommended 
list1 = [1, 2, 3] 
 
# Not recommended 
List1 = [ 1, 2, 3, ] 

Пример – 2

 
x = 5 
y = 6 
 
# Recommended 
print(x, y) 
 
# Not recommended 
print(x , y) 

Рекомендации по программированию

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

• Избегайте сравнения логических значений с помощью оператора эквивалентности

 
# Not recommended 
bool_value = 10 > 5 
if bool_value == True: 
    return '10 is bigger than 5' 

Мы не должны использовать оператор эквивалентности == для сравнения логических значений. Он может принимать только Истину или Ложь. Посмотрим на следующий пример.

 
# Recommended 
if my_bool: 
    return '10 is bigger than 5' 

Этот подход прост, поэтому PEP 8 поощряет его.

• Пустые последовательности ложны в операторах if

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

 
# Not recommended 
list1 = [] 
if not len(list1): 
    print('List is empty!') 

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

 
# Recommended 
list1 = [] 
if not list1: 
    print('List is empty!') 

Второй способ более уместен; вот почему PEP 8 поощряет это.

• Не используйте оператор not is in if

Есть два варианта проверить, имеет ли переменная определенное значение. В первом варианте x не равно None, как в следующем примере.

 
# Recommended 
if x is not None: 
    return 'x exists!' 

Второй вариант – оценить x как None и оператор if, основанный не на результате.

 
# Not recommended 
if not x is None: 
    return 'x exists!' 

Оба варианта верны, но первый прост, поэтому PEP 8 поддерживает его.

Заключение

Мы обсудили рекомендации PEP 8, чтобы код устранял двусмысленность и улучшал читаемость. Эти рекомендации улучшают код, особенно когда вы делитесь кодом с потенциальными сотрудниками или соавторами. Мы обсудили, что такое PEP и почему он используется, как писать код, совместимый с PEP 8. Кроме того, у нас есть краткое введение в соглашения об именах. Если вам нужна дополнительная информация о PEP 8, вы можете прочитать полную документацию или посетить pep8.org.

В борьбе за красивый и понятный код 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 таких проблем нет.

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

• Классы и исключения — LikeThis

• Константы  —  LIKE_THIS

• Переменные и аргументы — like_this

• Функции и методы —  тоже  like_this, но допускается и likeThis, если вы дописываете старый или чужой код, где уже задан такой формат.

Если имя аргумента вашей функции совпадает с зарезервированным в Python словом, не искажайте написание, но ставьте подчёркивание в конце. Вот так: «input_».

Проверка истинности без знаков равенства

Не используйте два знака равенства (==) для проверки булевых значений. Вместо этого используйте if или if not с именем объекта (например, переменной):

 if  i_have_apples:
# делаем то
 if not  key_obtained:
# делаем это

Если нужно сравнить что-то со значением «None», вместо операторов сравнения используйте is/is not.

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

Другое важное о Python в PEP 8

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

• При обработке исключений используйте синтаксис привязки имён, равно совместимый с Python 2 и 3:

try:
    something()
except Exception as exc:
    raise AnotherDamnError(str(exc))

• Старайтесь минимизировать количество кода в конструкциях  try… except. Это поможет избежать трудных в обнаружении ошибок.

• По возможности выбирайте синтаксис, который работает для всех реализаций Python: CPython, Jython, PyPy и других.

Автоматическая PEP проверка Python-кода

Пока вы создаете маленькие проекты, вычитывать код на ошибки и нарушения стиля не проблема. В работе над большими проектами  выручат скрипты автоматической проверки кода. PyCharm проверяет написанное «на лету». А если нужно поработать без IDE? На GitHub есть целый раздел Python Code Quality Authority, где хранятся утилиты для повышения качества кода, в том числе для проверки стиля на соответствие PEP 8: flake8, pycodestyle, pep8-naming. Когда будет нужно, вы сможете интегрировать Flake8 в свою среду разработки.

Осознанная необходимость

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

Если конкретный код при подгонке под стиль становится  уродливым, «такой хоккей нам не нужен». Например, если разбивка на строки по 72 символа усложняет чтение, PEP 8 предлагает удлинить строку до 80 или даже 100 символов — в зависимости от того, что удобно вам и вашей команде разработки. Чёткие ограничения действуют только для публичных проектов-библиотек.
Дополнительное чтение: если вы вошли во вкус, добавьте в свой список ещё и статью «Пиши как настоящий Питонист: идиоматика Python». Также советуем просмотреть вебинар о применении Python в реальном мире.