Стиль кода PEP 8 в Python

Введение

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

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

Понимание отступов и длины строк в PEP 8

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

Отступы (Indentation): PEP 8 рекомендует использовать 4 пробела на каждый уровень отступа. Это сильная конвенция в сообществе Python.

Длина строк (Line Length): PEP 8 предлагает ограничить все строки максимум 79 символами. Для строк документации (docstrings) и комментариев лимит составляет 72 символа. Это улучшает читаемость, особенно на небольших экранах или при сравнении кода бок о бок.

Давайте применим это на практике. В проводнике файлов слева найдите и откройте файл indentation_example.py. Код внутри демонстрирует правильные отступы для определений функций и многострочных выражений.

## Correct indentation using 4 spaces.
def long_function_name(
        var_one, var_two, var_three,
        var_four):
    print(var_one)

## Define some variables for demonstration.
var_one = "first"
var_two = "second"
var_three = "third"
var_four = "fourth"

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

## Using a hanging indent. The first line has no arguments,
## and subsequent lines are indented to distinguish them.
bar = long_function_name(
    var_one, var_two,
    var_three, var_four)

## A multi-line list.
my_list = [
    1, 2, 3,
    4, 5, 6,
]

## Calling the functions to produce output.
long_function_name("first call", "second", "third", "fourth")
foo = long_function_name("second call", "second", "third", "fourth")
bar = long_function_name("third call", "second", "third", "fourth")

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

python ~/project/indentation_example.py

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

first call
second call
third call

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

Практика использования пробелов и соглашений об именовании

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

Пробелы (Spacing):

• Используйте один пробел вокруг большинства операторов (=, +=, ==, <, >).
• Используйте пробел после запятых в списках, кортежах и аргументах функций.
• Избегайте лишних пробелов непосредственно внутри круглых скобок, квадратных скобок или фигурных скобок.

Соглашения об именовании (Naming Conventions):

• snake_case (змеиный_регистр): Используется для функций и переменных (например, my_function, user_name).
• PascalCase (ПаскальКейс): Используется для имен классов (например, MyClass).
• UPPERCASE_SNAKE_CASE (ВЕРХНИЙРЕГИСТРЗМЕИНЫЙ_РЕГИСТР): Используется для констант (например, MAX_CONNECTIONS).

Давайте посмотрим на эти правила в действии. В проводнике файлов откройте файл style_guide_example.py. Код включает примеры правильного использования пробелов и именования, с закомментированными некорректными версиями для сравнения.

## A constant
MAX_OVERFLOW = 100

## A class name in PascalCase
class MySampleClass:
    def __init__(self, name):
        ## A variable name in snake_case
        self.instance_name = name

    ## A function name in snake_case
    def sample_method(self, var_one, var_two):
        ## Correct spacing around operators and after comma
        result = var_one + var_two
        print(self.instance_name, result)

## --- Incorrect examples for comparison ---
## class mySampleClass:
##     def SampleMethod(self, varOne, varTwo):
##         result=varOne+varTwo
##         print(self.instance_name,result)

## Create an object and call the method
my_object = MySampleClass("TestObject")
my_object.sample_method(10, 5)

Сохраните файл, если вы внесли изменения, и запустите его из терминала:

python ~/project/style_guide_example.py

Вывод покажет имя объекта и результат вычисления:

TestObject 15

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

Использование autopep8 для автоматического форматирования

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

Сначала вам необходимо установить пакет autopep8. Откройте терминал и выполните следующую команду. sudo используется для установки пакета в системном масштабе.

sudo pip3 install autopep8

Начнется процесс установки, и вы должны увидеть вывод, подтверждающий успешную установку:

Collecting autopep8
...
Successfully installed autopep8-X.Y.Z

Далее давайте поработаем с файлом Python, в котором намеренно плохое форматирование. В проводнике файлов откройте unformatted_code.py и изучите его содержимое:

a=1
b=2;
def  my_function ( arg1 , arg2 = 0 ):
    result = arg1+arg2
    print( result)

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

Теперь давайте используем autopep8 для исправления. Флаг --in-place указывает инструменту изменять файл напрямую. Выполните эту команду в терминале:

autopep8 --in-place ~/project/unformatted_code.py

После завершения команды снова откройте unformatted_code.py в редакторе. Вы увидите, что код был автоматически приведен в порядок:

a = 1
b = 2


def my_function(arg1, arg2=0):
    result = arg1 + arg2
    print(result)

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

Сборка всего вместе: Рефакторинг скрипта

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

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

## This script calculates the area of a rectangle and prints it.
def CalculateArea(width,height):
    Area = width*height ## calculate area
    return Area

w = 10
h = 5
rectangle_area=CalculateArea(w,h)
print("The area of the rectangle is:",rectangle_area)

Ваша задача — вручную отредактировать этот код в редакторе, чтобы он соответствовал PEP 8. Ищите проблемы со следующим:

1. Именование функций: Имена функций должны использовать snake_case.
2. Именование переменных: Имена переменных также должны использовать snake_case.
3. Пробелы: Проверьте правильность пробелов вокруг операторов и после запятых.
4. Комментарии: Строчные комментарии должны иметь пробел после символа #.

Уделите время, чтобы самостоятельно провести рефакторинг кода. Когда закончите, ваш код должен выглядеть примерно так:

## This script calculates the area of a rectangle and prints it.
def calculate_area(width, height):
    """Calculate and return the area of a rectangle."""
    area = width * height  ## calculate area
    return area


w = 10
h = 5
rectangle_area = calculate_area(w, h)
print("The area of the rectangle is:", rectangle_area)

Обратите внимание на изменения: CalculateArea стало calculate_area, Area стало area, и были исправлены пробелы. Мы также добавили docstring (строку документации) к функции, что является лучшей практикой для объяснения того, что делает функция.

Сохраните изменения и запустите скрипт, чтобы убедиться, что он по-прежнему работает корректно:

python ~/project/refactor_challenge.py

Вывод должен быть следующим:

The area of the rectangle is: 50

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

Резюме

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